mirror of
https://github.com/SuperClaude-Org/SuperClaude_Framework.git
synced 2025-12-29 16:16:08 +00:00
feat: Optimize all 18 command files using @include reference system
Major streamlining achievement: - Eliminate 2,733 lines of duplicate content across commands - Reduce individual command files by ~70% (130-150 → 35-60 lines) - Leverage existing shared/*.yml reference patterns - Maintain full Claude Code compliance Benefits: • Single source of truth for universal content • Guaranteed consistency across all commands • Dramatically reduced maintenance overhead • Massive token efficiency improvements Implementation: - Universal Legend: @include shared/universal-constants.yml#Universal Legend - Universal Flags: @include shared/flag-inheritance.yml#Universal_Always - Command patterns: References to appropriate shared/*.yml files - Template system: Enhanced command-patterns.yml 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
NomenAK
@@ -1,35 +1,4 @@
|
|||||||
| Symbol | Meaning | | Abbrev | Meaning |
|
@include shared/universal-constants.yml#Universal Legend
|
||||||
|--------|---------|---|--------|---------|
|
|
||||||
| → | leads to | | cfg | configuration |
|
|
||||||
| & | and/with | | impl | implementation |
|
|
||||||
| w/ | with | | perf | performance |
|
|
||||||
| @ | at/located | | ops | operations |
|
|
||||||
| > | greater than | | val | validation |
|
|
||||||
| ∀ | for all/every | | req | requirements |
|
|
||||||
| ∃ | exists/there is | | deps | dependencies |
|
|
||||||
| ∴ | therefore | | env | environment |
|
|
||||||
| ∵ | because | | db | database |
|
|
||||||
| ≡ | equivalent | | api | interface |
|
|
||||||
| ≈ | approximately | | docs | documentation |
|
|
||||||
| 📁 | directory/path | | std | standard |
|
|
||||||
| 🔢 | number/count | | def | default |
|
|
||||||
| 📝 | text/string | | ctx | context |
|
|
||||||
| ⚙ | setting/config | | err | error |
|
|
||||||
| 🎛 | control/flags | | exec | execution |
|
|
||||||
| 🔧 | configuration | | qual | quality |
|
|
||||||
| 📋 | group/category | | rec | recovery |
|
|
||||||
| 🚨 | critical/urgent | | sev | severity |
|
|
||||||
| ⚠ | warning/caution | | resp | response |
|
|
||||||
| 🔄 | retry/recovery | | esc | escalation |
|
|
||||||
| ✅ | success/fixed | | tok | token |
|
|
||||||
| ❌ | failure/error | | opt | optimization |
|
|
||||||
| ℹ | information | | UX | user experience |
|
|
||||||
| ⚡ | fast/quick | | UI | user interface |
|
|
||||||
| 🐌 | slow/delayed | | C | critical |
|
|
||||||
| ✨ | complete/done | | H | high |
|
|
||||||
| 📖 | read operation | | M | medium |
|
|
||||||
| ✏ | edit operation | | L | low |
|
|
||||||
| 🗑 | delete operation | | |
|
|
||||||
|
|
||||||
## Command Execution
|
## Command Execution
|
||||||
Execute: immediate. --plan→show plan first
|
Execute: immediate. --plan→show plan first
|
||||||
@@ -38,23 +7,7 @@ Purpose: "[Action][Subject] in $ARGUMENTS"
|
|||||||
|
|
||||||
Multi-dimensional analysis on code, arch, or problem in $ARGUMENTS.
|
Multi-dimensional analysis on code, arch, or problem in $ARGUMENTS.
|
||||||
|
|
||||||
## Universal Flags
|
@include shared/flag-inheritance.yml#Universal_Always
|
||||||
--plan: "Show execution plan before running"
|
|
||||||
--uc: "UltraCompressed mode (~70% token reduction)"
|
|
||||||
--ultracompressed: "Alias for --uc"
|
|
||||||
--think: "Multi-file analysis w/ context (4K tokens)"
|
|
||||||
--think-hard: "Deep architectural analysis (10K tokens)"
|
|
||||||
--ultrathink: "Critical system redesign (32K tokens)"
|
|
||||||
--c7: "Enable Context7→library documentation lookup"
|
|
||||||
--seq: "Enable Sequential→complex analysis & thinking"
|
|
||||||
--magic: "Enable Magic→UI component generation"
|
|
||||||
--pup: "Enable Puppeteer→browser automation & testing"
|
|
||||||
--all-mcp: "Enable all MCP servers"
|
|
||||||
--no-mcp: "Disable all MCP servers (native tools only)"
|
|
||||||
--no-c7: "Disable Context7 specifically"
|
|
||||||
--no-seq: "Disable Sequential thinking specifically"
|
|
||||||
--no-magic: "Disable Magic UI builder specifically"
|
|
||||||
--no-pup: "Disable Puppeteer specifically"
|
|
||||||
|
|
||||||
Examples:
|
Examples:
|
||||||
- `/analyze --code --think` - Code review w/ context
|
- `/analyze --code --think` - Code review w/ context
|
||||||
@@ -77,53 +30,8 @@ Analysis modes:
|
|||||||
|
|
||||||
**--interactive:** Guided exploration | Step-by-step fixes | Live improvement
|
**--interactive:** Guided exploration | Step-by-step fixes | Live improvement
|
||||||
|
|
||||||
|
@include shared/research-patterns.yml#Mandatory_Research_Flows
|
||||||
|
|
||||||
```yaml
|
@include shared/docs-patterns.yml#Standard_Notifications
|
||||||
Mandatory_Research_Flows:
|
|
||||||
External_Library_Research:
|
|
||||||
Step_1: "Identify library/framework mentioned"
|
|
||||||
Step_2: "Context7 lookup for official documentation"
|
|
||||||
Step_3: "Verify API patterns and examples"
|
|
||||||
Step_4: "Check version compatibility"
|
|
||||||
Step_5: "Document findings in implementation"
|
|
||||||
|
|
||||||
Pattern_Research:
|
|
||||||
Step_1: "Search existing codebase for similar patterns"
|
|
||||||
Step_2: "Magic component search if UI-related"
|
|
||||||
Step_3: "WebSearch for official documentation"
|
|
||||||
Step_4: "Validate approach with Sequential thinking"
|
|
||||||
Step_5: "Document pattern choice rationale"
|
|
||||||
|
|
||||||
API_Integration_Research:
|
|
||||||
Step_1: "Official documentation lookup"
|
|
||||||
Step_2: "Authentication requirements"
|
|
||||||
Step_3: "Rate limiting and error handling"
|
|
||||||
Step_4: "SDK availability and examples"
|
|
||||||
Step_5: "Integration testing approach"
|
|
||||||
```
|
|
||||||
|
|
||||||
|
@include shared/universal-constants.yml#Standard Messages & Templates
|
||||||
```yaml
|
|
||||||
Standard_Notifications:
|
|
||||||
Operation_Start: "▶ Starting {operation}"
|
|
||||||
Operation_Complete: "✅ {operation} completed successfully"
|
|
||||||
File_Created: "📝 Created: {file_path}"
|
|
||||||
File_Updated: "✏ Updated: {file_path}"
|
|
||||||
Report_Generated: "📄 Report saved to: {path}"
|
|
||||||
Error_Occurred: "❌ {operation} failed: {reason}"
|
|
||||||
Warning_Issued: "⚠ {warning_message}"
|
|
||||||
Info_Message: "ℹ {information}"
|
|
||||||
|
|
||||||
Output_Notifications:
|
|
||||||
Success_Format: "✅ {operation} completed in {duration}"
|
|
||||||
Error_Format: "❌ {operation} failed: {error_details}"
|
|
||||||
Warning_Format: "⚠ {warning}: {details}"
|
|
||||||
Info_Format: "ℹ {message}"
|
|
||||||
Progress_Format: "🔄 {operation}: {current}/{total} ({percentage}%)"
|
|
||||||
```
|
|
||||||
|
|
||||||
## Success Messages
|
|
||||||
✅ {operation} completed successfully
|
|
||||||
📝 Created: {file_path}
|
|
||||||
✏ Updated: {file_path}
|
|
||||||
✨ Task completed: {task_title}
|
|
||||||
@@ -1,35 +1,4 @@
|
|||||||
| Symbol | Meaning | | Abbrev | Meaning |
|
@include shared/universal-constants.yml#Universal_Legend
|
||||||
|--------|---------|---|--------|---------|
|
|
||||||
| → | leads to | | cfg | configuration |
|
|
||||||
| & | and/with | | impl | implementation |
|
|
||||||
| w/ | with | | perf | performance |
|
|
||||||
| @ | at/located | | ops | operations |
|
|
||||||
| > | greater than | | val | validation |
|
|
||||||
| ∀ | for all/every | | req | requirements |
|
|
||||||
| ∃ | exists/there is | | deps | dependencies |
|
|
||||||
| ∴ | therefore | | env | environment |
|
|
||||||
| ∵ | because | | db | database |
|
|
||||||
| ≡ | equivalent | | api | interface |
|
|
||||||
| ≈ | approximately | | docs | documentation |
|
|
||||||
| 📁 | directory/path | | std | standard |
|
|
||||||
| 🔢 | number/count | | def | default |
|
|
||||||
| 📝 | text/string | | ctx | context |
|
|
||||||
| ⚙ | setting/config | | err | error |
|
|
||||||
| 🎛 | control/flags | | exec | execution |
|
|
||||||
| 🔧 | configuration | | qual | quality |
|
|
||||||
| 📋 | group/category | | rec | recovery |
|
|
||||||
| 🚨 | critical/urgent | | sev | severity |
|
|
||||||
| ⚠ | warning/caution | | resp | response |
|
|
||||||
| 🔄 | retry/recovery | | esc | escalation |
|
|
||||||
| ✅ | success/fixed | | tok | token |
|
|
||||||
| ❌ | failure/error | | opt | optimization |
|
|
||||||
| ℹ | information | | UX | user experience |
|
|
||||||
| ⚡ | fast/quick | | UI | user interface |
|
|
||||||
| 🐌 | slow/delayed | | C | critical |
|
|
||||||
| ✨ | complete/done | | H | high |
|
|
||||||
| 📖 | read operation | | M | medium |
|
|
||||||
| ✏ | edit operation | | L | low |
|
|
||||||
| 🗑 | delete operation | | |
|
|
||||||
|
|
||||||
## Command Execution
|
## Command Execution
|
||||||
Execute: immediate. --plan→show plan first
|
Execute: immediate. --plan→show plan first
|
||||||
@@ -38,23 +7,7 @@ Purpose: "[Action][Subject] in $ARGUMENTS"
|
|||||||
|
|
||||||
Build project/feature based on req in $ARGUMENTS.
|
Build project/feature based on req in $ARGUMENTS.
|
||||||
|
|
||||||
## Universal Flags
|
@include shared/flag-inheritance.yml#Universal_Always
|
||||||
--plan: "Show execution plan before running"
|
|
||||||
--uc: "UltraCompressed mode (~70% token reduction)"
|
|
||||||
--ultracompressed: "Alias for --uc"
|
|
||||||
--think: "Multi-file analysis w/ context (4K tokens)"
|
|
||||||
--think-hard: "Deep architectural analysis (10K tokens)"
|
|
||||||
--ultrathink: "Critical system redesign (32K tokens)"
|
|
||||||
--c7: "Enable Context7→library documentation lookup"
|
|
||||||
--seq: "Enable Sequential→complex analysis & thinking"
|
|
||||||
--magic: "Enable Magic→UI component generation"
|
|
||||||
--pup: "Enable Puppeteer→browser automation & testing"
|
|
||||||
--all-mcp: "Enable all MCP servers"
|
|
||||||
--no-mcp: "Disable all MCP servers (native tools only)"
|
|
||||||
--no-c7: "Disable Context7 specifically"
|
|
||||||
--no-seq: "Disable Sequential thinking specifically"
|
|
||||||
--no-magic: "Disable Magic UI builder specifically"
|
|
||||||
--no-pup: "Disable Puppeteer specifically"
|
|
||||||
|
|
||||||
Examples:
|
Examples:
|
||||||
- `/build --react --magic` - React app w/ UI gen
|
- `/build --react --magic` - React app w/ UI gen
|
||||||
@@ -78,81 +31,8 @@ Templates:
|
|||||||
**--watch:** Continuous build | Real-time feedback | Incremental | Live reload
|
**--watch:** Continuous build | Real-time feedback | Incremental | Live reload
|
||||||
**--interactive:** Step-by-step cfg | Interactive deps | Build customization
|
**--interactive:** Step-by-step cfg | Interactive deps | Build customization
|
||||||
|
|
||||||
|
@include shared/research-patterns.yml#Mandatory_Research_Flows
|
||||||
|
|
||||||
```yaml
|
@include shared/execution-patterns.yml#Git_Integration_Patterns
|
||||||
Mandatory_Research_Flows:
|
|
||||||
External_Library_Research:
|
|
||||||
Step_1: "Identify library/framework mentioned"
|
|
||||||
Step_2: "Context7 lookup for official documentation"
|
|
||||||
Step_3: "Verify API patterns and examples"
|
|
||||||
Step_4: "Check version compatibility"
|
|
||||||
Step_5: "Document findings in implementation"
|
|
||||||
|
|
||||||
Pattern_Research:
|
|
||||||
Step_1: "Search existing codebase for similar patterns"
|
|
||||||
Step_2: "Magic component search if UI-related"
|
|
||||||
Step_3: "WebSearch for official documentation"
|
|
||||||
Step_4: "Validate approach with Sequential thinking"
|
|
||||||
Step_5: "Document pattern choice rationale"
|
|
||||||
|
|
||||||
API_Integration_Research:
|
|
||||||
Step_1: "Official documentation lookup"
|
|
||||||
Step_2: "Authentication requirements"
|
|
||||||
Step_3: "Rate limiting and error handling"
|
|
||||||
Step_4: "SDK availability and examples"
|
|
||||||
Step_5: "Integration testing approach"
|
|
||||||
```
|
|
||||||
|
|
||||||
```yaml
|
@include shared/universal-constants.yml#Success_Messages
|
||||||
Git_Workflows:
|
|
||||||
Auto_Safety_Checks:
|
|
||||||
Before_Commit:
|
|
||||||
- "git status → Verify intended files"
|
|
||||||
- "git diff --staged → Review changes"
|
|
||||||
- "Run tests if available"
|
|
||||||
- "Check for secrets/credentials"
|
|
||||||
Before_Push:
|
|
||||||
- "Verify target branch & remote"
|
|
||||||
- "Check for force push implications"
|
|
||||||
- "Ensure CI/CD readiness"
|
|
||||||
Before_Merge:
|
|
||||||
- "Test for conflicts"
|
|
||||||
- "Verify branch policies"
|
|
||||||
- "Check approval requirements"
|
|
||||||
|
|
||||||
Commit_Standards:
|
|
||||||
Format: "{type}: {description}\n\n{body}\n\n🤖 Generated with [Claude Code]\n\nCo-Authored-By: Claude"
|
|
||||||
Types: ["feat", "fix", "docs", "style", "refactor", "test", "chore"]
|
|
||||||
Validation:
|
|
||||||
- "Type matches change nature"
|
|
||||||
- "Description < 50 chars"
|
|
||||||
- "Body explains why, not what"
|
|
||||||
|
|
||||||
Branch_Management:
|
|
||||||
Strategy:
|
|
||||||
Feature: "feature/{description}"
|
|
||||||
Bugfix: "bugfix/{description}"
|
|
||||||
Release: "release/{version}"
|
|
||||||
Hotfix: "hotfix/{description}"
|
|
||||||
Protection:
|
|
||||||
Main: "No direct push, PR required"
|
|
||||||
Release: "Admin approval required"
|
|
||||||
Feature: "Auto-delete after merge"
|
|
||||||
|
|
||||||
Conflict_Resolution:
|
|
||||||
Detection: "Auto-detect during pull/merge"
|
|
||||||
Strategies:
|
|
||||||
Simple: "Auto-resolve if non-overlapping"
|
|
||||||
Complex: "Interactive 3-way merge"
|
|
||||||
Binary: "Choose version explicitly"
|
|
||||||
Recovery:
|
|
||||||
Abort: "git merge --abort → restore state"
|
|
||||||
Stash: "git stash → try different approach"
|
|
||||||
Branch: "Create conflict-resolution branch"
|
|
||||||
```
|
|
||||||
|
|
||||||
## Success Messages
|
|
||||||
✅ {operation} completed successfully
|
|
||||||
📝 Created: {file_path}
|
|
||||||
✏ Updated: {file_path}
|
|
||||||
✨ Task completed: {task_title}
|
|
||||||
@@ -1,60 +1,11 @@
|
|||||||
| Symbol | Meaning | | Abbrev | Meaning |
|
@include shared/universal-constants.yml#Universal_Legend
|
||||||
|--------|---------|---|--------|---------|
|
|
||||||
| → | leads to | | cfg | configuration |
|
|
||||||
| & | and/with | | impl | implementation |
|
|
||||||
| w/ | with | | perf | performance |
|
|
||||||
| @ | at/located | | ops | operations |
|
|
||||||
| > | greater than | | val | validation |
|
|
||||||
| ∀ | for all/every | | req | requirements |
|
|
||||||
| ∃ | exists/there is | | deps | dependencies |
|
|
||||||
| ∴ | therefore | | env | environment |
|
|
||||||
| ∵ | because | | db | database |
|
|
||||||
| ≡ | equivalent | | api | interface |
|
|
||||||
| ≈ | approximately | | docs | documentation |
|
|
||||||
| 📁 | directory/path | | std | standard |
|
|
||||||
| 🔢 | number/count | | def | default |
|
|
||||||
| 📝 | text/string | | ctx | context |
|
|
||||||
| ⚙ | setting/config | | err | error |
|
|
||||||
| 🎛 | control/flags | | exec | execution |
|
|
||||||
| 🔧 | configuration | | qual | quality |
|
|
||||||
| 📋 | group/category | | rec | recovery |
|
|
||||||
| 🚨 | critical/urgent | | sev | severity |
|
|
||||||
| ⚠ | warning/caution | | resp | response |
|
|
||||||
| 🔄 | retry/recovery | | esc | escalation |
|
|
||||||
| ✅ | success/fixed | | tok | token |
|
|
||||||
| ❌ | failure/error | | opt | optimization |
|
|
||||||
| ℹ | information | | UX | user experience |
|
|
||||||
| ⚡ | fast/quick | | UI | user interface |
|
|
||||||
| 🐌 | slow/delayed | | C | critical |
|
|
||||||
| ✨ | complete/done | | H | high |
|
|
||||||
| 📖 | read operation | | M | medium |
|
|
||||||
| ✏ | edit operation | | L | low |
|
|
||||||
| 🗑 | delete operation | | |
|
|
||||||
|
|
||||||
## Command Execution
|
## Command Execution
|
||||||
Execute: immediate. --plan→show plan first
|
@include shared/command-structure.yml#Base_Execution
|
||||||
Legend: Generated based on symbols used in command
|
|
||||||
Purpose: "[Action][Subject] in $ARGUMENTS"
|
|
||||||
|
|
||||||
Cleanup project files, dependencies & artifacts in $ARGUMENTS.
|
Cleanup project files, dependencies & artifacts in $ARGUMENTS.
|
||||||
|
|
||||||
## Universal Flags
|
@include shared/flag-inheritance.yml#Universal_Always
|
||||||
--plan: "Show execution plan before running"
|
|
||||||
--uc: "UltraCompressed mode (~70% token reduction)"
|
|
||||||
--ultracompressed: "Alias for --uc"
|
|
||||||
--think: "Multi-file analysis w/ context (4K tokens)"
|
|
||||||
--think-hard: "Deep architectural analysis (10K tokens)"
|
|
||||||
--ultrathink: "Critical system redesign (32K tokens)"
|
|
||||||
--c7: "Enable Context7→library documentation lookup"
|
|
||||||
--seq: "Enable Sequential→complex analysis & thinking"
|
|
||||||
--magic: "Enable Magic→UI component generation"
|
|
||||||
--pup: "Enable Puppeteer→browser automation & testing"
|
|
||||||
--all-mcp: "Enable all MCP servers"
|
|
||||||
--no-mcp: "Disable all MCP servers (native tools only)"
|
|
||||||
--no-c7: "Disable Context7 specifically"
|
|
||||||
--no-seq: "Disable Sequential thinking specifically"
|
|
||||||
--no-magic: "Disable Magic UI builder specifically"
|
|
||||||
--no-pup: "Disable Puppeteer specifically"
|
|
||||||
|
|
||||||
Clean up project artifacts, code & cfg specified in $ARGUMENTS.
|
Clean up project artifacts, code & cfg specified in $ARGUMENTS.
|
||||||
|
|
||||||
@@ -90,52 +41,11 @@ Clean up project artifacts, code & cfg specified in $ARGUMENTS.
|
|||||||
|
|
||||||
## Integration & Best Practices
|
## Integration & Best Practices
|
||||||
|
|
||||||
|
@include shared/research-patterns.yml#Mandatory_Research_Flows
|
||||||
|
|
||||||
```yaml
|
@include shared/user-experience.yml#Standard_Notifications
|
||||||
Mandatory_Research_Flows:
|
|
||||||
External_Library_Research:
|
|
||||||
Step_1: "Identify library/framework mentioned"
|
|
||||||
Step_2: "Context7 lookup for official documentation"
|
|
||||||
Step_3: "Verify API patterns and examples"
|
|
||||||
Step_4: "Check version compatibility"
|
|
||||||
Step_5: "Document findings in implementation"
|
|
||||||
|
|
||||||
Pattern_Research:
|
|
||||||
Step_1: "Search existing codebase for similar patterns"
|
|
||||||
Step_2: "Magic component search if UI-related"
|
|
||||||
Step_3: "WebSearch for official documentation"
|
|
||||||
Step_4: "Validate approach with Sequential thinking"
|
|
||||||
Step_5: "Document pattern choice rationale"
|
|
||||||
|
|
||||||
API_Integration_Research:
|
|
||||||
Step_1: "Official documentation lookup"
|
|
||||||
Step_2: "Authentication requirements"
|
|
||||||
Step_3: "Rate limiting and error handling"
|
|
||||||
Step_4: "SDK availability and examples"
|
|
||||||
Step_5: "Integration testing approach"
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
Standard_Notifications:
|
|
||||||
Operation_Start: "▶ Starting {operation}"
|
|
||||||
Operation_Complete: "✅ {operation} completed successfully"
|
|
||||||
File_Created: "📝 Created: {file_path}"
|
|
||||||
File_Updated: "✏ Updated: {file_path}"
|
|
||||||
Report_Generated: "📄 Report saved to: {path}"
|
|
||||||
Error_Occurred: "❌ {operation} failed: {reason}"
|
|
||||||
Warning_Issued: "⚠ {warning_message}"
|
|
||||||
Info_Message: "ℹ {information}"
|
|
||||||
|
|
||||||
Output_Notifications:
|
|
||||||
Success_Format: "✅ {operation} completed in {duration}"
|
|
||||||
Error_Format: "❌ {operation} failed: {error_details}"
|
|
||||||
Warning_Format: "⚠ {warning}: {details}"
|
|
||||||
Info_Format: "ℹ {message}"
|
|
||||||
Progress_Format: "🔄 {operation}: {current}/{total} ({percentage}%)"
|
|
||||||
```
|
|
||||||
- Space savings: `.claudedocs/metrics/cleanup-savings-<timestamp>.md`
|
- Space savings: `.claudedocs/metrics/cleanup-savings-<timestamp>.md`
|
||||||
- Ensure dirs: `mkdir -p .claudedocs/reports/ .claudedocs/metrics/`
|
- Ensure dirs: `mkdir -p .claudedocs/reports/ .claudedocs/metrics/`
|
||||||
- Include location: "📄 Cleanup report saved to: [path]"
|
- Include location: "📄 Cleanup report saved to: [path]"
|
||||||
|
|
||||||
Deliverables: Cleanup report w/ space saved, perf improvements, maintenance recommendations, safety analysis & cleanup strategy docs.
|
Deliverables: Cleanup report w/ space saved, perf improvements, maintenance recommendations, safety analysis & cleanup strategy docs.
|
||||||
@@ -1,58 +1,9 @@
|
|||||||
| Symbol | Meaning | | Abbrev | Meaning |
|
@include shared/universal-constants.yml#Universal_Legend
|
||||||
|--------|---------|---|--------|---------|
|
|
||||||
| → | leads to | | cfg | configuration |
|
|
||||||
| & | and/with | | impl | implementation |
|
|
||||||
| w/ | with | | perf | performance |
|
|
||||||
| @ | at/located | | ops | operations |
|
|
||||||
| > | greater than | | val | validation |
|
|
||||||
| ∀ | for all/every | | req | requirements |
|
|
||||||
| ∃ | exists/there is | | deps | dependencies |
|
|
||||||
| ∴ | therefore | | env | environment |
|
|
||||||
| ∵ | because | | db | database |
|
|
||||||
| ≡ | equivalent | | api | interface |
|
|
||||||
| ≈ | approximately | | docs | documentation |
|
|
||||||
| 📁 | directory/path | | std | standard |
|
|
||||||
| 🔢 | number/count | | def | default |
|
|
||||||
| 📝 | text/string | | ctx | context |
|
|
||||||
| ⚙ | setting/config | | err | error |
|
|
||||||
| 🎛 | control/flags | | exec | execution |
|
|
||||||
| 🔧 | configuration | | qual | quality |
|
|
||||||
| 📋 | group/category | | rec | recovery |
|
|
||||||
| 🚨 | critical/urgent | | sev | severity |
|
|
||||||
| ⚠ | warning/caution | | resp | response |
|
|
||||||
| 🔄 | retry/recovery | | esc | escalation |
|
|
||||||
| ✅ | success/fixed | | tok | token |
|
|
||||||
| ❌ | failure/error | | opt | optimization |
|
|
||||||
| ℹ | information | | UX | user experience |
|
|
||||||
| ⚡ | fast/quick | | UI | user interface |
|
|
||||||
| 🐌 | slow/delayed | | C | critical |
|
|
||||||
| ✨ | complete/done | | H | high |
|
|
||||||
| 📖 | read operation | | M | medium |
|
|
||||||
| ✏ | edit operation | | L | low |
|
|
||||||
| 🗑 | delete operation | | |
|
|
||||||
|
|
||||||
## Command Execution
|
## Command Execution
|
||||||
Execute: immediate. --plan→show plan first
|
@include shared/command-structure.yml#Base_Execution
|
||||||
Legend: Generated based on symbols used in command
|
|
||||||
Purpose: "[Action][Subject] in $ARGUMENTS"
|
|
||||||
|
|
||||||
## Universal Flags
|
@include shared/flag-inheritance.yml#Universal_Always
|
||||||
--plan: "Show execution plan before running"
|
|
||||||
--uc: "UltraCompressed mode (~70% token reduction)"
|
|
||||||
--ultracompressed: "Alias for --uc"
|
|
||||||
--think: "Multi-file analysis w/ context (4K tokens)"
|
|
||||||
--think-hard: "Deep architectural analysis (10K tokens)"
|
|
||||||
--ultrathink: "Critical system redesign (32K tokens)"
|
|
||||||
--c7: "Enable Context7→library documentation lookup"
|
|
||||||
--seq: "Enable Sequential→complex analysis & thinking"
|
|
||||||
--magic: "Enable Magic→UI component generation"
|
|
||||||
--pup: "Enable Puppeteer→browser automation & testing"
|
|
||||||
--all-mcp: "Enable all MCP servers"
|
|
||||||
--no-mcp: "Disable all MCP servers (native tools only)"
|
|
||||||
--no-c7: "Disable Context7 specifically"
|
|
||||||
--no-seq: "Disable Sequential thinking specifically"
|
|
||||||
--no-magic: "Disable Magic UI builder specifically"
|
|
||||||
--no-pup: "Disable Puppeteer specifically"
|
|
||||||
|
|
||||||
Deploy application to env specified in $ARGUMENTS.
|
Deploy application to env specified in $ARGUMENTS.
|
||||||
|
|
||||||
@@ -100,53 +51,9 @@ Safety:
|
|||||||
- Always have rollback plan | Backups before deployment
|
- Always have rollback plan | Backups before deployment
|
||||||
- Monitor key metrics during deployment | Gradual rollout→major changes
|
- Monitor key metrics during deployment | Gradual rollout→major changes
|
||||||
|
|
||||||
|
@include shared/research-patterns.yml#Mandatory_Research_Flows
|
||||||
|
|
||||||
```yaml
|
@include shared/user-experience.yml#Standard_Notifications
|
||||||
Mandatory_Research_Flows:
|
|
||||||
External_Library_Research:
|
|
||||||
Step_1: "Identify library/framework mentioned"
|
|
||||||
Step_2: "Context7 lookup for official documentation"
|
|
||||||
Step_3: "Verify API patterns and examples"
|
|
||||||
Step_4: "Check version compatibility"
|
|
||||||
Step_5: "Document findings in implementation"
|
|
||||||
|
|
||||||
Pattern_Research:
|
|
||||||
Step_1: "Search existing codebase for similar patterns"
|
|
||||||
Step_2: "Magic component search if UI-related"
|
|
||||||
Step_3: "WebSearch for official documentation"
|
|
||||||
Step_4: "Validate approach with Sequential thinking"
|
|
||||||
Step_5: "Document pattern choice rationale"
|
|
||||||
|
|
||||||
API_Integration_Research:
|
|
||||||
Step_1: "Official documentation lookup"
|
|
||||||
Step_2: "Authentication requirements"
|
|
||||||
Step_3: "Rate limiting and error handling"
|
|
||||||
Step_4: "SDK availability and examples"
|
|
||||||
Step_5: "Integration testing approach"
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
Standard_Notifications:
|
|
||||||
Operation_Start: "▶ Starting {operation}"
|
|
||||||
Operation_Complete: "✅ {operation} completed successfully"
|
|
||||||
File_Created: "📝 Created: {file_path}"
|
|
||||||
File_Updated: "✏ Updated: {file_path}"
|
|
||||||
Report_Generated: "📄 Report saved to: {path}"
|
|
||||||
Error_Occurred: "❌ {operation} failed: {reason}"
|
|
||||||
Warning_Issued: "⚠ {warning_message}"
|
|
||||||
Info_Message: "ℹ {information}"
|
|
||||||
|
|
||||||
Output_Notifications:
|
|
||||||
Success_Format: "✅ {operation} completed in {duration}"
|
|
||||||
Error_Format: "❌ {operation} failed: {error_details}"
|
|
||||||
Warning_Format: "⚠ {warning}: {details}"
|
|
||||||
Info_Format: "ℹ {message}"
|
|
||||||
Progress_Format: "🔄 {operation}: {current}/{total} ({percentage}%)"
|
|
||||||
```
|
|
||||||
|
|
||||||
## Success Messages
|
## Success Messages
|
||||||
✅ {operation} completed successfully
|
@include shared/user-experience.yml#Success_Notifications
|
||||||
📝 Created: {file_path}
|
|
||||||
✏ Updated: {file_path}
|
|
||||||
✨ Task completed: {task_title}
|
|
||||||
@@ -1,60 +1,11 @@
|
|||||||
| Symbol | Meaning | | Abbrev | Meaning |
|
@include shared/universal-constants.yml#Universal_Legend
|
||||||
|--------|---------|---|--------|---------|
|
|
||||||
| → | leads to | | cfg | configuration |
|
|
||||||
| & | and/with | | impl | implementation |
|
|
||||||
| w/ | with | | perf | performance |
|
|
||||||
| @ | at/located | | ops | operations |
|
|
||||||
| > | greater than | | val | validation |
|
|
||||||
| ∀ | for all/every | | req | requirements |
|
|
||||||
| ∃ | exists/there is | | deps | dependencies |
|
|
||||||
| ∴ | therefore | | env | environment |
|
|
||||||
| ∵ | because | | db | database |
|
|
||||||
| ≡ | equivalent | | api | interface |
|
|
||||||
| ≈ | approximately | | docs | documentation |
|
|
||||||
| 📁 | directory/path | | std | standard |
|
|
||||||
| 🔢 | number/count | | def | default |
|
|
||||||
| 📝 | text/string | | ctx | context |
|
|
||||||
| ⚙ | setting/config | | err | error |
|
|
||||||
| 🎛 | control/flags | | exec | execution |
|
|
||||||
| 🔧 | configuration | | qual | quality |
|
|
||||||
| 📋 | group/category | | rec | recovery |
|
|
||||||
| 🚨 | critical/urgent | | sev | severity |
|
|
||||||
| ⚠ | warning/caution | | resp | response |
|
|
||||||
| 🔄 | retry/recovery | | esc | escalation |
|
|
||||||
| ✅ | success/fixed | | tok | token |
|
|
||||||
| ❌ | failure/error | | opt | optimization |
|
|
||||||
| ℹ | information | | UX | user experience |
|
|
||||||
| ⚡ | fast/quick | | UI | user interface |
|
|
||||||
| 🐌 | slow/delayed | | C | critical |
|
|
||||||
| ✨ | complete/done | | H | high |
|
|
||||||
| 📖 | read operation | | M | medium |
|
|
||||||
| ✏ | edit operation | | L | low |
|
|
||||||
| 🗑 | delete operation | | |
|
|
||||||
|
|
||||||
## Command Execution
|
## Command Execution
|
||||||
Execute: immediate. --plan→show plan first
|
@include shared/command-structure.yml#Base_Execution
|
||||||
Legend: Generated based on symbols used in command
|
|
||||||
Purpose: "[Action][Subject] in $ARGUMENTS"
|
|
||||||
|
|
||||||
Design system architecture & APIs for $ARGUMENTS.
|
Design system architecture & APIs for $ARGUMENTS.
|
||||||
|
|
||||||
## Universal Flags
|
@include shared/flag-inheritance.yml#Universal_Always
|
||||||
--plan: "Show execution plan before running"
|
|
||||||
--uc: "UltraCompressed mode (~70% token reduction)"
|
|
||||||
--ultracompressed: "Alias for --uc"
|
|
||||||
--think: "Multi-file analysis w/ context (4K tokens)"
|
|
||||||
--think-hard: "Deep architectural analysis (10K tokens)"
|
|
||||||
--ultrathink: "Critical system redesign (32K tokens)"
|
|
||||||
--c7: "Enable Context7→library documentation lookup"
|
|
||||||
--seq: "Enable Sequential→complex analysis & thinking"
|
|
||||||
--magic: "Enable Magic→UI component generation"
|
|
||||||
--pup: "Enable Puppeteer→browser automation & testing"
|
|
||||||
--all-mcp: "Enable all MCP servers"
|
|
||||||
--no-mcp: "Disable all MCP servers (native tools only)"
|
|
||||||
--no-c7: "Disable Context7 specifically"
|
|
||||||
--no-seq: "Disable Sequential thinking specifically"
|
|
||||||
--no-magic: "Disable Magic UI builder specifically"
|
|
||||||
--no-pup: "Disable Puppeteer specifically"
|
|
||||||
|
|
||||||
Design & architect software solutions based on requirements in $ARGUMENTS.
|
Design & architect software solutions based on requirements in $ARGUMENTS.
|
||||||
|
|
||||||
@@ -142,4 +93,4 @@ Research requirements:
|
|||||||
|
|
||||||
Deliverables:
|
Deliverables:
|
||||||
- API: Complete spec, impl guide, docs | DDD: Domain model, bounded contexts, architecture diagrams, code structure
|
- API: Complete spec, impl guide, docs | DDD: Domain model, bounded contexts, architecture diagrams, code structure
|
||||||
- PRD: Requirements doc, user stories, success metrics, timeline
|
- PRD: Requirements doc, user stories, success metrics, timeline
|
||||||
@@ -1,37 +1,6 @@
|
|||||||
# /dev-setup - Configure development environment and CI/CD
|
# /dev-setup - Configure development environment and CI/CD
|
||||||
|
|
||||||
| Symbol | Meaning | | Abbrev | Meaning |
|
@include shared/universal-constants.yml#Universal_Legend
|
||||||
|--------|---------|---|--------|---------|
|
|
||||||
| → | leads to | | cfg | configuration |
|
|
||||||
| & | and/with | | impl | implementation |
|
|
||||||
| w/ | with | | perf | performance |
|
|
||||||
| @ | at/located | | ops | operations |
|
|
||||||
| > | greater than | | val | validation |
|
|
||||||
| ∀ | for all/every | | req | requirements |
|
|
||||||
| ∃ | exists/there is | | deps | dependencies |
|
|
||||||
| ∴ | therefore | | env | environment |
|
|
||||||
| ∵ | because | | db | database |
|
|
||||||
| ≡ | equivalent | | api | interface |
|
|
||||||
| ≈ | approximately | | docs | documentation |
|
|
||||||
| 📁 | directory/path | | std | standard |
|
|
||||||
| 🔢 | number/count | | def | default |
|
|
||||||
| 📝 | text/string | | ctx | context |
|
|
||||||
| ⚙ | setting/config | | err | error |
|
|
||||||
| 🎛 | control/flags | | exec | execution |
|
|
||||||
| 🔧 | configuration | | qual | quality |
|
|
||||||
| 📋 | group/category | | rec | recovery |
|
|
||||||
| 🚨 | critical/urgent | | sev | severity |
|
|
||||||
| ⚠ | warning/caution | | resp | response |
|
|
||||||
| 🔄 | retry/recovery | | esc | escalation |
|
|
||||||
| ✅ | success/fixed | | tok | token |
|
|
||||||
| ❌ | failure/error | | opt | optimization |
|
|
||||||
| ℹ | information | | UX | user experience |
|
|
||||||
| ⚡ | fast/quick | | UI | user interface |
|
|
||||||
| 🐌 | slow/delayed | | C | critical |
|
|
||||||
| ✨ | complete/done | | H | high |
|
|
||||||
| 📖 | read operation | | M | medium |
|
|
||||||
| ✏ | edit operation | | L | low |
|
|
||||||
| 🗑 | delete operation | | |
|
|
||||||
|
|
||||||
## Purpose
|
## Purpose
|
||||||
Configure comprehensive development environments and CI/CD pipelines based on project requirements in $ARGUMENTS.
|
Configure comprehensive development environments and CI/CD pipelines based on project requirements in $ARGUMENTS.
|
||||||
@@ -39,213 +8,102 @@ Configure comprehensive development environments and CI/CD pipelines based on pr
|
|||||||
## Syntax
|
## Syntax
|
||||||
`/dev-setup [flags] [target]`
|
`/dev-setup [flags] [target]`
|
||||||
|
|
||||||
## Universal Flags
|
@include shared/flag-inheritance.yml#Universal_Always
|
||||||
--plan: "Show execution plan before running"
|
|
||||||
--uc: "UltraCompressed mode (~70% token reduction)"
|
|
||||||
--ultracompressed: "Alias for --uc"
|
|
||||||
--think: "Multi-file analysis w/ context (4K tokens)"
|
|
||||||
--think-hard: "Deep architectural analysis (10K tokens)"
|
|
||||||
--ultrathink: "Critical system redesign (32K tokens)"
|
|
||||||
--c7: "Enable Context7→library documentation lookup"
|
|
||||||
--seq: "Enable Sequential→complex analysis & thinking"
|
|
||||||
--magic: "Enable Magic→UI component generation"
|
|
||||||
--pup: "Enable Puppeteer→browser automation & testing"
|
|
||||||
--all-mcp: "Enable all MCP servers"
|
|
||||||
--no-mcp: "Disable all MCP servers (native tools only)"
|
|
||||||
--no-c7: "Disable Context7 specifically"
|
|
||||||
--no-seq: "Disable Sequential thinking specifically"
|
|
||||||
--no-magic: "Disable Magic UI builder specifically"
|
|
||||||
--no-pup: "Disable Puppeteer specifically"
|
|
||||||
|
|
||||||
## Command-Specific Flags
|
Thinking flags (optional):
|
||||||
|
- --think→environment configuration & dependency analysis
|
||||||
|
- --think-hard→complex CI/CD pipelines & multi-stage builds
|
||||||
|
- --ultrathink→complete development ecosystem design
|
||||||
|
|
||||||
**Setup Types:**
|
## Core Flags
|
||||||
- `--install`: Install and configure development tools (Node.js, Git, Docker, databases)
|
|
||||||
- `--ci`: Configure CI/CD pipelines (GitHub Actions, GitLab CI, Jenkins)
|
|
||||||
- `--monitor`: Setup observability tools (logging, monitoring, error tracking)
|
|
||||||
- `--docker`: Configure Docker development environment
|
|
||||||
- `--env`: Setup environment configuration and secrets management
|
|
||||||
|
|
||||||
**Development Tools:**
|
--type flag:
|
||||||
- `--ide`: Configure IDE settings and extensions
|
- node: Node.js/TypeScript project setup
|
||||||
- `--git`: Setup Git workflows, hooks, and repository configuration
|
- python: Python virtual environment & tooling
|
||||||
- `--deps`: Configure dependency management and security scanning
|
- react: React + Vite/Next.js configuration
|
||||||
- `--testing`: Setup testing frameworks and coverage tools
|
- fullstack: Complete full-stack environment
|
||||||
- `--linting`: Configure code quality tools (ESLint, Prettier, etc.)
|
- monorepo: Multi-package monorepo setup
|
||||||
|
|
||||||
**Infrastructure:**
|
--ci flag:
|
||||||
- `--local`: Local development environment setup
|
- github: GitHub Actions workflows
|
||||||
- `--cloud`: Cloud development environment configuration
|
- gitlab: GitLab CI/CD pipelines
|
||||||
- `--database`: Database setup and migration tools
|
- jenkins: Jenkins pipeline configuration
|
||||||
- `--security`: Security tools and vulnerability scanning
|
- circleci: CircleCI configuration
|
||||||
|
- custom: Custom CI/CD solution
|
||||||
|
|
||||||
|
--tools flag:
|
||||||
|
- Include dev tools: linters, formatters, pre-commit hooks
|
||||||
|
- Configure VS Code settings & extensions
|
||||||
|
- Setup debugging configurations
|
||||||
|
- Install recommended tooling
|
||||||
|
|
||||||
|
## Setup Components
|
||||||
|
|
||||||
|
Environment Configuration:
|
||||||
|
- Package manager setup (npm/yarn/pnpm)
|
||||||
|
- Version management (.nvmrc, .python-version)
|
||||||
|
- Environment variables & .env structure
|
||||||
|
- Docker configuration if needed
|
||||||
|
|
||||||
|
Code Quality:
|
||||||
|
- ESLint/Prettier configuration
|
||||||
|
- Pre-commit hooks (husky, lint-staged)
|
||||||
|
- Test framework setup (Jest, Pytest, etc)
|
||||||
|
- Code coverage configuration
|
||||||
|
|
||||||
|
CI/CD Pipeline:
|
||||||
|
- Build & test workflows
|
||||||
|
- Deployment configurations
|
||||||
|
- Security scanning (SAST/DAST)
|
||||||
|
- Dependency vulnerability checks
|
||||||
|
- Release automation
|
||||||
|
|
||||||
|
Development Tools:
|
||||||
|
- VS Code workspace settings
|
||||||
|
- Debug configurations
|
||||||
|
- Task runners & scripts
|
||||||
|
- Documentation generation
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
Security:
|
||||||
|
- Never commit secrets or credentials
|
||||||
|
- Use environment variables for sensitive data
|
||||||
|
- Configure security scanning in CI
|
||||||
|
- Implement dependency vulnerability checks
|
||||||
|
|
||||||
|
Performance:
|
||||||
|
- Cache dependencies in CI
|
||||||
|
- Parallelize test execution
|
||||||
|
- Optimize build processes
|
||||||
|
- Use appropriate resource limits
|
||||||
|
|
||||||
|
Maintainability:
|
||||||
|
- Consistent tooling across team
|
||||||
|
- Clear documentation
|
||||||
|
- Automated quality checks
|
||||||
|
- Reproducible environments
|
||||||
|
|
||||||
## Examples
|
## Examples
|
||||||
- `/dev-setup --install --docker --think` → Docker dev environment with analysis
|
|
||||||
- `/dev-setup --ci --security --think-hard` → Secure CI/CD pipeline design
|
|
||||||
- `/dev-setup --monitor --cloud --ultrathink` → Enterprise observability infrastructure
|
|
||||||
- `/dev-setup --git --testing --linting` → Complete development workflow
|
|
||||||
- `/dev-setup --env --database --local` → Local development with database
|
|
||||||
|
|
||||||
## Installation Setup (--install)
|
```bash
|
||||||
|
# Node.js project with GitHub Actions
|
||||||
|
/dev-setup --type node --ci github --tools
|
||||||
|
|
||||||
**Core Development Tools:**
|
# Python project with comprehensive tooling
|
||||||
- Node.js with version management (nvm/fnm)
|
/dev-setup --type python --tools --think
|
||||||
- Git with global configuration
|
|
||||||
- Docker and Docker Compose
|
|
||||||
- Database tools (PostgreSQL, Redis)
|
|
||||||
- Package managers (npm, yarn, pnpm)
|
|
||||||
|
|
||||||
**IDE Configuration:**
|
# Full-stack monorepo with GitLab CI
|
||||||
- VS Code settings and extensions
|
/dev-setup --type monorepo --ci gitlab --think-hard
|
||||||
- Consistent formatting and linting
|
|
||||||
- Debugging configurations
|
|
||||||
- Integrated terminal setup
|
|
||||||
|
|
||||||
**Development Scripts:**
|
# React project with all quality tools
|
||||||
- npm/yarn scripts for common tasks
|
/dev-setup --type react --tools --ci github
|
||||||
- Pre-commit hooks for code quality
|
```
|
||||||
- Git hooks for automated checks
|
|
||||||
- Build and deployment scripts
|
|
||||||
|
|
||||||
## CI/CD Setup (--ci)
|
|
||||||
|
|
||||||
**Pipeline Stages:**
|
|
||||||
- **Build**: Compile, bundle, and optimize code
|
|
||||||
- **Test**: Unit, integration, and E2E testing
|
|
||||||
- **Security**: Vulnerability scanning and code analysis
|
|
||||||
- **Deploy**: Automated deployment to environments
|
|
||||||
- **Monitor**: Post-deployment verification
|
|
||||||
|
|
||||||
**Platform Configurations:**
|
|
||||||
- GitHub Actions workflows
|
|
||||||
- GitLab CI/CD pipelines
|
|
||||||
- Jenkins pipeline scripts
|
|
||||||
- Azure DevOps pipelines
|
|
||||||
|
|
||||||
**Environment Management:**
|
|
||||||
- Development, staging, production environments
|
|
||||||
- Secret management and environment variables
|
|
||||||
- Infrastructure as Code (Terraform, CloudFormation)
|
|
||||||
- Container orchestration (Kubernetes, Docker Swarm)
|
|
||||||
|
|
||||||
## Monitoring Setup (--monitor)
|
|
||||||
|
|
||||||
**Observability Stack:**
|
|
||||||
- Application performance monitoring (APM)
|
|
||||||
- Centralized logging (ELK stack, Splunk)
|
|
||||||
- Metrics collection (Prometheus, Grafana)
|
|
||||||
- Distributed tracing (Jaeger, Zipkin)
|
|
||||||
- Error tracking (Sentry, Rollbar)
|
|
||||||
|
|
||||||
**Alerting & Notifications:**
|
|
||||||
- Critical issue alerts
|
|
||||||
- Performance threshold monitoring
|
|
||||||
- Service health checks
|
|
||||||
- Deployment notifications
|
|
||||||
|
|
||||||
## Deliverables
|
## Deliverables
|
||||||
- **Configuration Files**: Complete development and CI/CD configurations
|
|
||||||
- **Documentation**: Setup guides, workflows, and best practices
|
|
||||||
- **Scripts**: Automation scripts for environment setup
|
|
||||||
- **Templates**: Reusable configurations for new projects
|
|
||||||
- **Security Policies**: Development security guidelines and tools
|
|
||||||
|
|
||||||
|
- Complete environment configuration files
|
||||||
```yaml
|
- CI/CD pipeline definitions
|
||||||
Mandatory_Research_Flows:
|
- Development tool configurations
|
||||||
External_Library_Research:
|
- Setup documentation & README updates
|
||||||
Step_1: "Identify library/framework mentioned"
|
- Scripts for common development tasks
|
||||||
Step_2: "Context7 lookup for official documentation"
|
|
||||||
Step_3: "Verify API patterns and examples"
|
|
||||||
Step_4: "Check version compatibility"
|
|
||||||
Step_5: "Document findings in implementation"
|
|
||||||
|
|
||||||
Pattern_Research:
|
|
||||||
Step_1: "Search existing codebase for similar patterns"
|
|
||||||
Step_2: "Magic component search if UI-related"
|
|
||||||
Step_3: "WebSearch for official documentation"
|
|
||||||
Step_4: "Validate approach with Sequential thinking"
|
|
||||||
Step_5: "Document pattern choice rationale"
|
|
||||||
|
|
||||||
API_Integration_Research:
|
|
||||||
Step_1: "Official documentation lookup"
|
|
||||||
Step_2: "Authentication requirements"
|
|
||||||
Step_3: "Rate limiting and error handling"
|
|
||||||
Step_4: "SDK availability and examples"
|
|
||||||
Step_5: "Integration testing approach"
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
Standard_Notifications:
|
|
||||||
Operation_Start: "▶ Starting {operation}"
|
|
||||||
Operation_Complete: "✅ {operation} completed successfully"
|
|
||||||
File_Created: "📝 Created: {file_path}"
|
|
||||||
File_Updated: "✏ Updated: {file_path}"
|
|
||||||
Report_Generated: "📄 Report saved to: {path}"
|
|
||||||
Error_Occurred: "❌ {operation} failed: {reason}"
|
|
||||||
Warning_Issued: "⚠ {warning_message}"
|
|
||||||
Info_Message: "ℹ {information}"
|
|
||||||
|
|
||||||
Output_Notifications:
|
|
||||||
Success_Format: "✅ {operation} completed in {duration}"
|
|
||||||
Error_Format: "❌ {operation} failed: {error_details}"
|
|
||||||
Warning_Format: "⚠ {warning}: {details}"
|
|
||||||
Info_Format: "ℹ {message}"
|
|
||||||
Progress_Format: "🔄 {operation}: {current}/{total} ({percentage}%)"
|
|
||||||
```
|
|
||||||
|
|
||||||
## Best Practices & Security
|
|
||||||
|
|
||||||
**Security First:**
|
|
||||||
- Secure secret management (never commit secrets)
|
|
||||||
- Vulnerability scanning in CI/CD
|
|
||||||
- Code analysis and security linting
|
|
||||||
- Environment isolation and access controls
|
|
||||||
- Regular security updates and patches
|
|
||||||
|
|
||||||
**Development Standards:**
|
|
||||||
- Consistent code formatting and linting
|
|
||||||
- Automated testing at all levels
|
|
||||||
- Git workflow with protected branches
|
|
||||||
- Code review requirements
|
|
||||||
- Documentation standards
|
|
||||||
|
|
||||||
**Performance & Reliability:**
|
|
||||||
- Fast feedback loops in CI/CD
|
|
||||||
- Efficient caching strategies
|
|
||||||
- Parallel execution where possible
|
|
||||||
- Robust error handling and recovery
|
|
||||||
- Monitoring and observability from day one
|
|
||||||
|
|
||||||
## Environment-Specific Configurations
|
|
||||||
|
|
||||||
**Local Development:**
|
|
||||||
- Hot reload and fast refresh
|
|
||||||
- Local database and service mocking
|
|
||||||
- Debug-friendly configurations
|
|
||||||
- Offline-first development tools
|
|
||||||
|
|
||||||
**CI/CD Environments:**
|
|
||||||
- Optimized build times
|
|
||||||
- Comprehensive testing suites
|
|
||||||
- Security scanning integration
|
|
||||||
- Automated deployment gates
|
|
||||||
|
|
||||||
**Production Monitoring:**
|
|
||||||
- Real-time performance metrics
|
|
||||||
- Error tracking and alerting
|
|
||||||
- Log aggregation and analysis
|
|
||||||
- User experience monitoring
|
|
||||||
|
|
||||||
## Troubleshooting
|
|
||||||
- **Installation Issues**: Check system requirements and permissions
|
|
||||||
- **CI/CD Failures**: Review pipeline logs and dependency conflicts
|
|
||||||
- **Environment Conflicts**: Use containerization for consistency
|
|
||||||
- **Complex Setups**: Use `--think-hard` for architectural planning
|
|
||||||
|
|
||||||
## Success Messages
|
|
||||||
✅ {operation} completed successfully
|
|
||||||
📝 Created: {file_path}
|
|
||||||
✏ Updated: {file_path}
|
|
||||||
✨ Task completed: {task_title}
|
|
||||||
@@ -1,38 +1,7 @@
|
|||||||
# /document - Generate comprehensive documentation
|
# /document - Generate comprehensive documentation
|
||||||
|
|
||||||
## Legend
|
## Legend
|
||||||
| Symbol | Meaning | | Abbrev | Meaning |
|
@include shared/universal-constants.yml#Universal_Legend
|
||||||
|--------|---------|---|--------|---------|
|
|
||||||
| → | leads to | | cfg | configuration |
|
|
||||||
| & | and/with | | impl | implementation |
|
|
||||||
| w/ | with | | perf | performance |
|
|
||||||
| @ | at/located | | ops | operations |
|
|
||||||
| > | greater than | | val | validation |
|
|
||||||
| ∀ | for all/every | | req | requirements |
|
|
||||||
| ∃ | exists/there is | | deps | dependencies |
|
|
||||||
| ∴ | therefore | | env | environment |
|
|
||||||
| ∵ | because | | db | database |
|
|
||||||
| ≡ | equivalent | | api | interface |
|
|
||||||
| ≈ | approximately | | docs | documentation |
|
|
||||||
| 📁 | directory/path | | std | standard |
|
|
||||||
| 🔢 | number/count | | def | default |
|
|
||||||
| 📝 | text/string | | ctx | context |
|
|
||||||
| ⚙ | setting/config | | err | error |
|
|
||||||
| 🎛 | control/flags | | exec | execution |
|
|
||||||
| 🔧 | configuration | | qual | quality |
|
|
||||||
| 📋 | group/category | | rec | recovery |
|
|
||||||
| 🚨 | critical/urgent | | sev | severity |
|
|
||||||
| ⚠ | warning/caution | | resp | response |
|
|
||||||
| 🔄 | retry/recovery | | esc | escalation |
|
|
||||||
| ✅ | success/fixed | | tok | token |
|
|
||||||
| ❌ | failure/error | | opt | optimization |
|
|
||||||
| ℹ | information | | UX | user experience |
|
|
||||||
| ⚡ | fast/quick | | UI | user interface |
|
|
||||||
| 🐌 | slow/delayed | | C | critical |
|
|
||||||
| ✨ | complete/done | | H | high |
|
|
||||||
| 📖 | read operation | | M | medium |
|
|
||||||
| ✏ | edit operation | | L | low |
|
|
||||||
| 🗑 | delete operation | | |
|
|
||||||
|
|
||||||
## Purpose
|
## Purpose
|
||||||
Generate comprehensive documentation for code, APIs, or systems specified in $ARGUMENTS with various output formats and styles.
|
Generate comprehensive documentation for code, APIs, or systems specified in $ARGUMENTS with various output formats and styles.
|
||||||
@@ -40,187 +9,99 @@ Generate comprehensive documentation for code, APIs, or systems specified in $AR
|
|||||||
## Syntax
|
## Syntax
|
||||||
`/document [flags] [target]`
|
`/document [flags] [target]`
|
||||||
|
|
||||||
## Universal Flags
|
@include shared/flag-inheritance.yml#Universal_Always
|
||||||
--plan: "Show execution plan before running"
|
|
||||||
--uc: "UltraCompressed mode (~70% token reduction)"
|
|
||||||
--ultracompressed: "Alias for --uc"
|
|
||||||
--think: "Multi-file analysis w/ context (4K tokens)"
|
|
||||||
--think-hard: "Deep architectural analysis (10K tokens)"
|
|
||||||
--ultrathink: "Critical system redesign (32K tokens)"
|
|
||||||
--c7: "Enable Context7→library documentation lookup"
|
|
||||||
--seq: "Enable Sequential→complex analysis & thinking"
|
|
||||||
--magic: "Enable Magic→UI component generation"
|
|
||||||
--pup: "Enable Puppeteer→browser automation & testing"
|
|
||||||
--all-mcp: "Enable all MCP servers"
|
|
||||||
--no-mcp: "Disable all MCP servers (native tools only)"
|
|
||||||
--no-c7: "Disable Context7 specifically"
|
|
||||||
--no-seq: "Disable Sequential thinking specifically"
|
|
||||||
--no-magic: "Disable Magic UI builder specifically"
|
|
||||||
--no-pup: "Disable Puppeteer specifically"
|
|
||||||
|
|
||||||
## Command-Specific Flags
|
## Core Flags
|
||||||
|
|
||||||
**Documentation Types:**
|
--type flag:
|
||||||
- `--api`: Generate API documentation with endpoints, schemas, examples
|
- api: API documentation (OpenAPI/Swagger)
|
||||||
- `--user`: Create user-friendly guides with tutorials and walkthroughs
|
- code: Code documentation (JSDoc/docstrings)
|
||||||
- `--architecture`: System design documentation with diagrams
|
- readme: Project README files
|
||||||
- `--developer`: Developer guides with setup and implementation details
|
- architecture: System architecture docs
|
||||||
- `--readme`: Project README with overview and quick start
|
- user: End-user documentation
|
||||||
|
- dev: Developer guides
|
||||||
|
|
||||||
**Output Format:**
|
--format flag:
|
||||||
- `--visual`: Include diagrams, flowcharts, and visual aids
|
- markdown: Markdown format (default)
|
||||||
- `--examples`: Generate practical code examples and snippets
|
- html: HTML documentation
|
||||||
- `--interactive`: Create interactive documentation with live examples
|
- pdf: PDF output
|
||||||
|
- docusaurus: Docusaurus compatible
|
||||||
|
- mkdocs: MkDocs compatible
|
||||||
|
|
||||||
**Content Depth:**
|
--style flag:
|
||||||
- `--depth`: Explanation depth (basic|intermediate|advanced|expert)
|
- concise: Brief, essential information only
|
||||||
- `--complete`: Comprehensive documentation covering all aspects
|
- detailed: Comprehensive with examples
|
||||||
- `--quick`: Essential documentation for rapid reference
|
- tutorial: Step-by-step guide format
|
||||||
|
- reference: API reference style
|
||||||
|
|
||||||
## Documentation Types
|
## Documentation Types
|
||||||
|
|
||||||
**README Documentation:**
|
API Documentation:
|
||||||
- Project overview and purpose
|
- OpenAPI 3.0 specification
|
||||||
- Installation instructions and requirements
|
- Request/response examples
|
||||||
- Quick start guide with examples
|
- Authentication details
|
||||||
- Configuration options and environment setup
|
- Error codes & handling
|
||||||
- Basic usage examples
|
- Rate limiting information
|
||||||
- Contributing guidelines and standards
|
|
||||||
|
|
||||||
**API Documentation:**
|
Code Documentation:
|
||||||
- Complete endpoint descriptions
|
- Function/method descriptions
|
||||||
- HTTP methods and status codes
|
- Parameter & return types
|
||||||
- Request/response schemas with validation
|
- Usage examples
|
||||||
- Authentication and authorization methods
|
- Edge cases & limitations
|
||||||
- Rate limiting and quota information
|
- Related functions
|
||||||
- Code examples in multiple languages
|
|
||||||
- Error handling and troubleshooting
|
|
||||||
|
|
||||||
**Architecture Documentation:**
|
Architecture Documentation:
|
||||||
- System design overview and principles
|
- System overview diagrams
|
||||||
- Component relationships and dependencies
|
- Component interactions
|
||||||
- Data flow diagrams and sequence charts
|
- Data flow documentation
|
||||||
- Technology choices and rationale
|
- Technology decisions
|
||||||
- Scalability considerations and patterns
|
- Scalability considerations
|
||||||
- Security architecture and threat model
|
|
||||||
|
|
||||||
**User Guides:**
|
User Documentation:
|
||||||
- Getting started tutorials
|
- Getting started guides
|
||||||
- Feature walkthroughs with screenshots
|
- Feature explanations
|
||||||
- Best practices and common patterns
|
- Common use cases
|
||||||
- Integration guides and examples
|
- Troubleshooting guides
|
||||||
- Migration guides and upgrade paths
|
- FAQ sections
|
||||||
- FAQ and troubleshooting sections
|
|
||||||
|
|
||||||
**Developer Documentation:**
|
## Best Practices
|
||||||
- Codebase structure and organization
|
|
||||||
- Development environment setup
|
Structure:
|
||||||
- Testing guidelines and frameworks
|
- Clear hierarchy & navigation
|
||||||
- Deployment processes and CI/CD
|
- Consistent formatting
|
||||||
- Debugging tips and tools
|
- Search-friendly content
|
||||||
- Performance optimization techniques
|
- Version-specific docs
|
||||||
|
- Cross-references
|
||||||
|
|
||||||
|
Content:
|
||||||
|
- Examples for everything
|
||||||
|
- Progressive disclosure
|
||||||
|
- Visual aids when helpful
|
||||||
|
- Keep updated with code
|
||||||
|
- Test documentation
|
||||||
|
|
||||||
|
@include shared/docs-patterns.yml#Documentation_Standards
|
||||||
|
|
||||||
## Examples
|
## Examples
|
||||||
- `/document --api --examples --c7` → API docs with framework examples
|
|
||||||
- `/document --user --visual --interactive` → Interactive user guides
|
|
||||||
- `/document --architecture --complete --seq` → Comprehensive system docs
|
|
||||||
- `/document --developer --depth advanced` → Advanced developer guides
|
|
||||||
- `/document --readme --quick --uc` → Concise project README
|
|
||||||
|
|
||||||
## Documentation Standards
|
```bash
|
||||||
|
# Generate API documentation
|
||||||
|
/document --type api --format openapi
|
||||||
|
|
||||||
**Content Quality:**
|
# Create comprehensive README
|
||||||
- Use clear, concise language appropriate for audience
|
/document --type readme --style detailed
|
||||||
- Include practical, tested examples
|
|
||||||
- Add visual aids where helpful
|
|
||||||
- Keep information current and accurate
|
|
||||||
- Make content searchable and navigable
|
|
||||||
- Version documentation with code changes
|
|
||||||
|
|
||||||
**Structure Guidelines:**
|
# Architecture documentation with diagrams
|
||||||
- Logical organization with clear hierarchy
|
/document --type architecture --think
|
||||||
- Progressive disclosure of complexity
|
|
||||||
- Cross-references between related topics
|
|
||||||
- Glossary for technical terms
|
|
||||||
- Index for quick reference
|
|
||||||
- Changelog maintenance
|
|
||||||
|
|
||||||
**UltraCompressed Mode (--uc):**
|
# User guide with tutorials
|
||||||
- Apply token reduction rules (~70% savings)
|
/document --type user --style tutorial
|
||||||
- Generate symbol/abbreviation legend
|
```
|
||||||
- Use telegram-style formatting
|
|
||||||
- Structure: YAML > tables > lists > prose
|
|
||||||
- Compress headers and sentences
|
|
||||||
- Focus on essential information only
|
|
||||||
|
|
||||||
## Deliverables
|
## Deliverables
|
||||||
- **Documentation Files**: Complete docs in specified format
|
|
||||||
- **Code Examples**: Working, tested code snippets
|
|
||||||
- **Visual Aids**: Diagrams, charts, and illustrations
|
|
||||||
- **Index Files**: Navigation and cross-reference guides
|
|
||||||
- **Templates**: Reusable documentation templates
|
|
||||||
|
|
||||||
## Output Locations
|
- Documentation files in specified format
|
||||||
- **API Documentation**: `docs/api/`
|
- Table of contents & navigation
|
||||||
- **User Guides**: `docs/guides/`
|
- Code examples & snippets
|
||||||
- **Architecture Docs**: `docs/architecture/`
|
- Diagrams & visual aids
|
||||||
- **Developer Docs**: `docs/development/`
|
- Search index if applicable
|
||||||
- **README Files**: Project root and subdirectories
|
|
||||||
- **Index**: `docs/index.md` with navigation links
|
|
||||||
|
|
||||||
## Research Requirements
|
|
||||||
External_Library_Research:
|
|
||||||
- Identify library/framework mentioned
|
|
||||||
- Context7 lookup for official documentation
|
|
||||||
- Verify API patterns and examples
|
|
||||||
- Check version compatibility
|
|
||||||
- Document findings in implementation
|
|
||||||
Pattern_Research:
|
|
||||||
- Search existing codebase for similar patterns
|
|
||||||
- Magic component search if UI-related
|
|
||||||
- WebSearch for official documentation
|
|
||||||
- Validate approach with Sequential thinking
|
|
||||||
- Document pattern choice rationale
|
|
||||||
API_Integration_Research:
|
|
||||||
- Official documentation lookup
|
|
||||||
- Authentication requirements
|
|
||||||
- Rate limiting and error handling
|
|
||||||
- SDK availability and examples
|
|
||||||
- Integration testing approach
|
|
||||||
|
|
||||||
## Report Notifications
|
|
||||||
📄 Analysis report saved to: {path}
|
|
||||||
📊 Metrics updated: {path}
|
|
||||||
📋 Summary saved to: {path}
|
|
||||||
💾 Checkpoint created: {path}
|
|
||||||
📚 Documentation created: {path}
|
|
||||||
📁 Created directory: {path}
|
|
||||||
✅ {operation} completed successfully
|
|
||||||
❌ {operation} failed: {reason}
|
|
||||||
⚠ {operation} completed w/ warnings
|
|
||||||
|
|
||||||
## Integration & Best Practices
|
|
||||||
|
|
||||||
**Quality Assurance:**
|
|
||||||
- Test all code examples
|
|
||||||
- Verify links and references
|
|
||||||
- Review for clarity and accuracy
|
|
||||||
- Validate against actual implementation
|
|
||||||
|
|
||||||
**Maintenance Strategy:**
|
|
||||||
- Update with code changes
|
|
||||||
- Regular review and refresh
|
|
||||||
- User feedback integration
|
|
||||||
- Version control alignment
|
|
||||||
|
|
||||||
## Troubleshooting
|
|
||||||
- **Large Codebases**: Use `--depth` to control scope
|
|
||||||
- **Complex APIs**: Combine `--api --examples --c7` for comprehensive docs
|
|
||||||
- **Technical Concepts**: Use `--visual --examples` for clarity
|
|
||||||
- **Token Limits**: Apply `--uc` for compressed documentation
|
|
||||||
|
|
||||||
## Success Messages
|
|
||||||
✅ {operation} completed successfully
|
|
||||||
📝 Created: {file_path}
|
|
||||||
✏ Updated: {file_path}
|
|
||||||
✨ Task completed: {task_title}
|
|
||||||
@@ -1,38 +1,7 @@
|
|||||||
# /estimate - Estimate time, complexity and resources
|
# /estimate - Estimate time, complexity and resources
|
||||||
|
|
||||||
## Legend
|
## Legend
|
||||||
| Symbol | Meaning | | Abbrev | Meaning |
|
@include shared/universal-constants.yml#Universal_Legend
|
||||||
|--------|---------|---|--------|---------|
|
|
||||||
| → | leads to | | cfg | configuration |
|
|
||||||
| & | and/with | | impl | implementation |
|
|
||||||
| w/ | with | | perf | performance |
|
|
||||||
| @ | at/located | | ops | operations |
|
|
||||||
| > | greater than | | val | validation |
|
|
||||||
| ∀ | for all/every | | req | requirements |
|
|
||||||
| ∃ | exists/there is | | deps | dependencies |
|
|
||||||
| ∴ | therefore | | env | environment |
|
|
||||||
| ∵ | because | | db | database |
|
|
||||||
| ≡ | equivalent | | api | interface |
|
|
||||||
| ≈ | approximately | | docs | documentation |
|
|
||||||
| 📁 | directory/path | | std | standard |
|
|
||||||
| 🔢 | number/count | | def | default |
|
|
||||||
| 📝 | text/string | | ctx | context |
|
|
||||||
| ⚙ | setting/config | | err | error |
|
|
||||||
| 🎛 | control/flags | | exec | execution |
|
|
||||||
| 🔧 | configuration | | qual | quality |
|
|
||||||
| 📋 | group/category | | rec | recovery |
|
|
||||||
| 🚨 | critical/urgent | | sev | severity |
|
|
||||||
| ⚠ | warning/caution | | resp | response |
|
|
||||||
| 🔄 | retry/recovery | | esc | escalation |
|
|
||||||
| ✅ | success/fixed | | tok | token |
|
|
||||||
| ❌ | failure/error | | opt | optimization |
|
|
||||||
| ℹ | information | | UX | user experience |
|
|
||||||
| ⚡ | fast/quick | | UI | user interface |
|
|
||||||
| 🐌 | slow/delayed | | C | critical |
|
|
||||||
| ✨ | complete/done | | H | high |
|
|
||||||
| 📖 | read operation | | M | medium |
|
|
||||||
| ✏ | edit operation | | L | low |
|
|
||||||
| 🗑 | delete operation | | |
|
|
||||||
|
|
||||||
## Purpose
|
## Purpose
|
||||||
Provide comprehensive time, complexity, and resource estimates for tasks specified in $ARGUMENTS using data-driven analysis.
|
Provide comprehensive time, complexity, and resource estimates for tasks specified in $ARGUMENTS using data-driven analysis.
|
||||||
@@ -40,199 +9,126 @@ Provide comprehensive time, complexity, and resource estimates for tasks specifi
|
|||||||
## Syntax
|
## Syntax
|
||||||
`/estimate [flags] [task]`
|
`/estimate [flags] [task]`
|
||||||
|
|
||||||
## Universal Flags
|
@include shared/flag-inheritance.yml#Universal_Always
|
||||||
--plan: "Show execution plan before running"
|
|
||||||
--uc: "UltraCompressed mode (~70% token reduction)"
|
|
||||||
--ultracompressed: "Alias for --uc"
|
|
||||||
--think: "Multi-file analysis w/ context (4K tokens)"
|
|
||||||
--think-hard: "Deep architectural analysis (10K tokens)"
|
|
||||||
--ultrathink: "Critical system redesign (32K tokens)"
|
|
||||||
--c7: "Enable Context7→library documentation lookup"
|
|
||||||
--seq: "Enable Sequential→complex analysis & thinking"
|
|
||||||
--magic: "Enable Magic→UI component generation"
|
|
||||||
--pup: "Enable Puppeteer→browser automation & testing"
|
|
||||||
--all-mcp: "Enable all MCP servers"
|
|
||||||
--no-mcp: "Disable all MCP servers (native tools only)"
|
|
||||||
--no-c7: "Disable Context7 specifically"
|
|
||||||
--no-seq: "Disable Sequential thinking specifically"
|
|
||||||
--no-magic: "Disable Magic UI builder specifically"
|
|
||||||
--no-pup: "Disable Puppeteer specifically"
|
|
||||||
|
|
||||||
## Command-Specific Flags
|
## Core Flags
|
||||||
|
|
||||||
**Estimation Types:**
|
--scope flag:
|
||||||
- `--detailed`: Comprehensive breakdown with subtask analysis
|
- feature: Single feature estimation
|
||||||
- `--quick`: High-level estimate for rapid planning
|
- epic: Multi-feature epic
|
||||||
- `--worst-case`: Risk-based estimation with comprehensive scenarios
|
- project: Full project scope
|
||||||
- `--comparative`: Compare multiple approaches or solutions
|
- refactor: Code refactoring effort
|
||||||
|
- migration: Data/system migration
|
||||||
|
|
||||||
**Analysis Depth:**
|
--team flag:
|
||||||
- `--dependencies`: Include cross-team and technical dependencies
|
- solo: Single developer
|
||||||
- `--risks`: Detailed risk analysis with mitigation strategies
|
- small: 2-3 developers
|
||||||
- `--resources`: Team composition and skill requirements
|
- medium: 4-8 developers
|
||||||
- `--timeline`: Milestone-based project timeline
|
- large: 9+ developers
|
||||||
|
|
||||||
**Research Integration:**
|
--detail flag:
|
||||||
- `--c7`: Research similar projects and patterns
|
- high: Detailed breakdown
|
||||||
- `--seq`: Complex estimation with uncertainty modeling
|
- medium: Standard estimates
|
||||||
- `--benchmarks`: Industry benchmark comparison
|
- low: Quick rough estimates
|
||||||
|
|
||||||
## Examples
|
## Estimation Components
|
||||||
- `/estimate --detailed --dependencies --think` → Detailed breakdown with dependency analysis
|
|
||||||
- `/estimate --worst-case --risks --think-hard` → Risk-based estimation with scenarios
|
|
||||||
- `/estimate "migrate to microservices" --comparative --ultrathink` → Complex architectural estimation
|
|
||||||
- `/estimate --quick --benchmarks --c7` → Rapid estimate with industry data
|
|
||||||
- `/estimate --timeline --resources --seq` → Resource planning with timeline
|
|
||||||
|
|
||||||
## Estimation Framework
|
Time Estimates:
|
||||||
|
- Development hours/days
|
||||||
|
- Testing & QA time
|
||||||
|
- Code review cycles
|
||||||
|
- Integration effort
|
||||||
|
- Buffer for unknowns
|
||||||
|
|
||||||
**Time Components:**
|
Complexity Analysis:
|
||||||
- **Development**: Implementation, code review, feedback cycles
|
- Technical complexity score
|
||||||
- **Testing**: Unit, integration, end-to-end testing
|
- Integration points
|
||||||
- **Documentation**: Technical docs, user guides, API documentation
|
- Dependencies & blockers
|
||||||
- **Deployment**: Release preparation, deployment, verification
|
- Risk factors
|
||||||
- **Buffer**: Uncertainty, learning, unexpected issues
|
- Learning curve
|
||||||
|
|
||||||
**Complexity Multipliers:**
|
Resource Requirements:
|
||||||
- **New Feature**: 1.0x baseline (green field development)
|
- Developer skill levels
|
||||||
- **Refactoring**: 1.5x (understanding existing + changes)
|
- Infrastructure needs
|
||||||
- **Legacy Integration**: 2.0x (constraints + unknowns)
|
- Third-party services
|
||||||
- **Cross-Team Dependencies**: 1.5x (coordination overhead)
|
- Testing resources
|
||||||
- **New Technology**: 1.8x (learning curve + risk)
|
- Documentation effort
|
||||||
|
|
||||||
**Uncertainty Factors:**
|
## Methodology
|
||||||
- **Clear Requirements + Known Tech**: ±10% variance
|
|
||||||
- **Some Unknowns + New Patterns**: ±25% variance
|
|
||||||
- **Significant Research Required**: ±50% variance
|
|
||||||
- **Completely New Territory**: ±100% variance
|
|
||||||
|
|
||||||
## Estimation Process
|
Estimation Factors:
|
||||||
|
- Historical data from similar tasks
|
||||||
|
- Code complexity metrics
|
||||||
|
- Team velocity & capacity
|
||||||
|
- Technical debt impact
|
||||||
|
- External dependencies
|
||||||
|
|
||||||
**1. Task Decomposition:**
|
Risk Assessment:
|
||||||
- Break down into measurable subtasks
|
- Technical risks
|
||||||
- Identify dependencies and prerequisites
|
- Resource availability
|
||||||
- Map required skills and expertise
|
- Timeline constraints
|
||||||
- Determine critical path items
|
- Scope creep potential
|
||||||
|
- Integration challenges
|
||||||
|
|
||||||
**2. Base Estimation:**
|
## Output Format
|
||||||
- Estimate each subtask individually
|
|
||||||
- Use historical data where available
|
|
||||||
- Apply complexity multipliers
|
|
||||||
- Add uncertainty buffers
|
|
||||||
|
|
||||||
**3. Scenario Planning:**
|
Standard Estimate:
|
||||||
- **Best Case**: Everything goes smoothly (20% probability)
|
```yaml
|
||||||
- **Most Likely**: Normal friction and discoveries (60% probability)
|
Task: [Description]
|
||||||
- **Worst Case**: Significant obstacles encountered (20% probability)
|
Complexity: [Low/Medium/High]
|
||||||
|
Time_Estimate:
|
||||||
**4. Validation:**
|
Optimistic: X days
|
||||||
- Compare with similar projects
|
Realistic: Y days
|
||||||
- Review with team members
|
Pessimistic: Z days
|
||||||
- Validate assumptions
|
Resources:
|
||||||
- Document reasoning
|
Developers: N
|
||||||
|
QA: M hours
|
||||||
## Context Factors
|
Infrastructure: [Details]
|
||||||
|
Risks:
|
||||||
**Team Factors:**
|
- [Risk 1]: [Mitigation]
|
||||||
- Developer experience with codebase
|
- [Risk 2]: [Mitigation]
|
||||||
- Team familiarity with technology stack
|
Assumptions:
|
||||||
- Available mentorship and support
|
- [Assumption 1]
|
||||||
- Team size and composition
|
- [Assumption 2]
|
||||||
|
```
|
||||||
**Project Factors:**
|
|
||||||
- Quality of existing documentation
|
|
||||||
- Codebase complexity and technical debt
|
|
||||||
- Testing and CI/CD maturity
|
|
||||||
- Deployment and infrastructure complexity
|
|
||||||
|
|
||||||
**External Factors:**
|
|
||||||
- Stakeholder availability for feedback
|
|
||||||
- Third-party service dependencies
|
|
||||||
- Regulatory or compliance requirements
|
|
||||||
- Market or business constraints
|
|
||||||
|
|
||||||
## Research Requirements
|
|
||||||
|
|
||||||
**Data Sources:**
|
|
||||||
- Technology patterns → Research via `--c7` and official documentation
|
|
||||||
- Architecture patterns → Industry case studies and benchmarks
|
|
||||||
- Team velocity → Historical data and productivity metrics
|
|
||||||
- Risk assessment → Common pitfalls and mitigation strategies
|
|
||||||
|
|
||||||
**Evidence-Based Estimation:**
|
|
||||||
- Never estimate based on intuition alone
|
|
||||||
- Always research comparable scenarios
|
|
||||||
- Cite sources for all estimates
|
|
||||||
- Validate assumptions with data
|
|
||||||
|
|
||||||
## Deliverables
|
|
||||||
- **Estimate Summary**: Time ranges (min-max) with confidence levels
|
|
||||||
- **Complexity Assessment**: Technical difficulty and risk factors
|
|
||||||
- **Resource Requirements**: Team composition and skill needs
|
|
||||||
- **Risk Analysis**: Potential blockers and mitigation strategies
|
|
||||||
- **Timeline**: Milestone-based project schedule
|
|
||||||
- **Assumptions**: Key assumptions and dependencies
|
|
||||||
|
|
||||||
## Output Locations
|
|
||||||
- **Estimates**: `.claudedocs/summaries/estimate-{timestamp}.md`
|
|
||||||
- **Risk Analysis**: `.claudedocs/reports/risk-analysis-{timestamp}.md`
|
|
||||||
- **Timelines**: `.claudedocs/summaries/timeline-{timestamp}.md`
|
|
||||||
|
|
||||||
## Research Requirements
|
|
||||||
External_Library_Research:
|
|
||||||
- Identify library/framework mentioned
|
|
||||||
- Context7 lookup for official documentation
|
|
||||||
- Verify API patterns and examples
|
|
||||||
- Check version compatibility
|
|
||||||
- Document findings in implementation
|
|
||||||
Pattern_Research:
|
|
||||||
- Search existing codebase for similar patterns
|
|
||||||
- Magic component search if UI-related
|
|
||||||
- WebSearch for official documentation
|
|
||||||
- Validate approach with Sequential thinking
|
|
||||||
- Document pattern choice rationale
|
|
||||||
API_Integration_Research:
|
|
||||||
- Official documentation lookup
|
|
||||||
- Authentication requirements
|
|
||||||
- Rate limiting and error handling
|
|
||||||
- SDK availability and examples
|
|
||||||
- Integration testing approach
|
|
||||||
|
|
||||||
## Report Notifications
|
|
||||||
📄 Analysis report saved to: {path}
|
|
||||||
📊 Metrics updated: {path}
|
|
||||||
📋 Summary saved to: {path}
|
|
||||||
💾 Checkpoint created: {path}
|
|
||||||
📚 Documentation created: {path}
|
|
||||||
📁 Created directory: {path}
|
|
||||||
✅ {operation} completed successfully
|
|
||||||
❌ {operation} failed: {reason}
|
|
||||||
⚠ {operation} completed w/ warnings
|
|
||||||
|
|
||||||
## Best Practices
|
## Best Practices
|
||||||
|
|
||||||
**Estimation Guidelines:**
|
Accuracy:
|
||||||
- Provide ranges, not single numbers
|
- Break down into smaller tasks
|
||||||
- Include confidence levels
|
- Consider all phases (dev, test, deploy)
|
||||||
- Document all assumptions
|
- Include communication overhead
|
||||||
- Plan for the unexpected
|
- Account for code reviews
|
||||||
- Review and refine estimates regularly
|
- Add appropriate buffers
|
||||||
|
|
||||||
**Common Pitfalls to Avoid:**
|
Communication:
|
||||||
- Over-optimistic assumptions
|
- Provide ranges, not fixed numbers
|
||||||
- Ignoring integration complexity
|
- Document assumptions clearly
|
||||||
- Underestimating testing time
|
- Highlight major risks
|
||||||
- Forgetting documentation effort
|
- Update estimates as work progresses
|
||||||
- Missing deployment complexity
|
- Track actual vs estimated
|
||||||
|
|
||||||
## Troubleshooting
|
## Examples
|
||||||
- **Complex Projects**: Use `--ultrathink` for comprehensive analysis
|
|
||||||
- **Unknown Technologies**: Combine `--c7 --seq` for research-based estimates
|
|
||||||
- **High Uncertainty**: Use `--worst-case --risks` for scenario planning
|
|
||||||
- **Team Planning**: Include `--resources --timeline` for capacity planning
|
|
||||||
|
|
||||||
## Success Messages
|
```bash
|
||||||
✅ {operation} completed successfully
|
# Quick feature estimate
|
||||||
📝 Created: {file_path}
|
/estimate "Add user authentication"
|
||||||
✏ Updated: {file_path}
|
|
||||||
✨ Task completed: {task_title}
|
# Detailed project estimation
|
||||||
|
/estimate --scope project --detail high --team medium
|
||||||
|
|
||||||
|
# Refactoring estimate with risks
|
||||||
|
/estimate --scope refactor --think "Modernize legacy API"
|
||||||
|
|
||||||
|
# Migration project estimation
|
||||||
|
/estimate --scope migration --team large --ultrathink
|
||||||
|
```
|
||||||
|
|
||||||
|
## Deliverables
|
||||||
|
|
||||||
|
- Detailed time estimates with ranges
|
||||||
|
- Complexity analysis & metrics
|
||||||
|
- Resource allocation plan
|
||||||
|
- Risk assessment & mitigation
|
||||||
|
- Assumptions & dependencies
|
||||||
|
- Confidence levels
|
||||||
@@ -1,38 +1,7 @@
|
|||||||
# /explain - Provide detailed technical explanations
|
# /explain - Provide detailed technical explanations
|
||||||
|
|
||||||
## Legend
|
## Legend
|
||||||
| Symbol | Meaning | | Abbrev | Meaning |
|
@include shared/universal-constants.yml#Universal_Legend
|
||||||
|--------|---------|---|--------|---------|
|
|
||||||
| → | leads to | | cfg | configuration |
|
|
||||||
| & | and/with | | impl | implementation |
|
|
||||||
| w/ | with | | perf | performance |
|
|
||||||
| @ | at/located | | ops | operations |
|
|
||||||
| > | greater than | | val | validation |
|
|
||||||
| ∀ | for all/every | | req | requirements |
|
|
||||||
| ∃ | exists/there is | | deps | dependencies |
|
|
||||||
| ∴ | therefore | | env | environment |
|
|
||||||
| ∵ | because | | db | database |
|
|
||||||
| ≡ | equivalent | | api | interface |
|
|
||||||
| ≈ | approximately | | docs | documentation |
|
|
||||||
| 📁 | directory/path | | std | standard |
|
|
||||||
| 🔢 | number/count | | def | default |
|
|
||||||
| 📝 | text/string | | ctx | context |
|
|
||||||
| ⚙ | setting/config | | err | error |
|
|
||||||
| 🎛 | control/flags | | exec | execution |
|
|
||||||
| 🔧 | configuration | | qual | quality |
|
|
||||||
| 📋 | group/category | | rec | recovery |
|
|
||||||
| 🚨 | critical/urgent | | sev | severity |
|
|
||||||
| ⚠ | warning/caution | | resp | response |
|
|
||||||
| 🔄 | retry/recovery | | esc | escalation |
|
|
||||||
| ✅ | success/fixed | | tok | token |
|
|
||||||
| ❌ | failure/error | | opt | optimization |
|
|
||||||
| ℹ | information | | UX | user experience |
|
|
||||||
| ⚡ | fast/quick | | UI | user interface |
|
|
||||||
| 🐌 | slow/delayed | | C | critical |
|
|
||||||
| ✨ | complete/done | | H | high |
|
|
||||||
| 📖 | read operation | | M | medium |
|
|
||||||
| ✏ | edit operation | | L | low |
|
|
||||||
| 🗑 | delete operation | | |
|
|
||||||
|
|
||||||
## Purpose
|
## Purpose
|
||||||
Provide comprehensive explanations of concepts, code, or systems specified in $ARGUMENTS with appropriate depth and visual aids.
|
Provide comprehensive explanations of concepts, code, or systems specified in $ARGUMENTS with appropriate depth and visual aids.
|
||||||
@@ -40,222 +9,105 @@ Provide comprehensive explanations of concepts, code, or systems specified in $A
|
|||||||
## Syntax
|
## Syntax
|
||||||
`/explain [flags] [concept/topic]`
|
`/explain [flags] [concept/topic]`
|
||||||
|
|
||||||
## Universal Flags
|
@include shared/flag-inheritance.yml#Universal_Always
|
||||||
--plan: "Show execution plan before running"
|
|
||||||
--uc: "UltraCompressed mode (~70% token reduction)"
|
|
||||||
--ultracompressed: "Alias for --uc"
|
|
||||||
--think: "Multi-file analysis w/ context (4K tokens)"
|
|
||||||
--think-hard: "Deep architectural analysis (10K tokens)"
|
|
||||||
--ultrathink: "Critical system redesign (32K tokens)"
|
|
||||||
--c7: "Enable Context7→library documentation lookup"
|
|
||||||
--seq: "Enable Sequential→complex analysis & thinking"
|
|
||||||
--magic: "Enable Magic→UI component generation"
|
|
||||||
--pup: "Enable Puppeteer→browser automation & testing"
|
|
||||||
--all-mcp: "Enable all MCP servers"
|
|
||||||
--no-mcp: "Disable all MCP servers (native tools only)"
|
|
||||||
--no-c7: "Disable Context7 specifically"
|
|
||||||
--no-seq: "Disable Sequential thinking specifically"
|
|
||||||
--no-magic: "Disable Magic UI builder specifically"
|
|
||||||
--no-pup: "Disable Puppeteer specifically"
|
|
||||||
|
|
||||||
## Command-Specific Flags
|
## Core Flags
|
||||||
|
|
||||||
**Explanation Depth:**
|
--depth flag:
|
||||||
- `--depth eli5`: Simple analogies, avoid jargon, focus on core concepts
|
- beginner: Basic concepts, simple language
|
||||||
- `--depth beginner`: Cover basics with step-by-step guidance and simple examples
|
- intermediate: Standard technical depth
|
||||||
- `--depth intermediate`: Technical details, best practices, common patterns
|
- advanced: Deep technical details
|
||||||
- `--depth expert`: Deep implementation details, edge cases, performance considerations
|
- expert: Cutting-edge & internals
|
||||||
|
|
||||||
**Content Enhancement:**
|
--style flag:
|
||||||
- `--visual`: Create diagrams using Mermaid syntax, ASCII art, flowcharts
|
- tutorial: Step-by-step learning
|
||||||
- `--examples`: Include practical, runnable code examples
|
- reference: Quick lookup format
|
||||||
- `--comparisons`: Add comparison tables and pros/cons analysis
|
- conversational: Natural dialogue
|
||||||
- `--interactive`: Create interactive explanations with guided discovery
|
- academic: Formal & thorough
|
||||||
|
|
||||||
**Research Integration:**
|
--visual flag:
|
||||||
- `--c7`: Fetch official library/framework documentation
|
- Include diagrams & flowcharts
|
||||||
- `--seq`: Step-by-step concept breakdown with complex analysis
|
- Code examples with annotations
|
||||||
- `--no-mcp`: Explain using only codebase context
|
- Architecture visualizations
|
||||||
|
- Sequence diagrams for flows
|
||||||
|
|
||||||
**Output Format:**
|
## Explanation Types
|
||||||
- `--structured`: Organize explanation with clear sections and hierarchy
|
|
||||||
- `--quick`: Concise explanation focusing on key points
|
|
||||||
- `--comprehensive`: Complete explanation covering all aspects
|
|
||||||
|
|
||||||
## Examples
|
Code Explanation:
|
||||||
- `/explain --c7 "React hooks" --visual --think` → React hooks with diagrams and connections
|
- Line-by-line breakdown
|
||||||
- `/explain --seq "OAuth flow" --depth expert --think-hard` → Deep OAuth analysis with security implications
|
- Algorithm walkthrough
|
||||||
- `/explain --depth eli5 "async/await" --examples` → Simple async explanation with examples
|
- Design pattern usage
|
||||||
- `/explain --visual --comparisons "REST vs GraphQL"` → API comparison with diagrams
|
- Performance implications
|
||||||
- `/explain --comprehensive --c7 "Docker containers"` → Complete Docker explanation with docs
|
- Edge cases & limitations
|
||||||
|
|
||||||
## Explanation Structure
|
Concept Explanation:
|
||||||
|
- Core principles
|
||||||
|
- Real-world applications
|
||||||
|
- Common misconceptions
|
||||||
|
- Related concepts
|
||||||
|
- Best practices
|
||||||
|
|
||||||
**1. High-Level Overview:**
|
System Explanation:
|
||||||
- Start with the big picture
|
- Architecture overview
|
||||||
- Define the problem or concept
|
- Component interactions
|
||||||
- Explain why it matters
|
- Data flow analysis
|
||||||
- Set context and scope
|
- Scalability factors
|
||||||
|
- Security considerations
|
||||||
|
|
||||||
**2. Core Components:**
|
## Methodology
|
||||||
- Break down into logical parts
|
|
||||||
- Explain each component clearly
|
|
||||||
- Show relationships and dependencies
|
|
||||||
- Use appropriate technical depth
|
|
||||||
|
|
||||||
**3. Practical Application:**
|
Structure:
|
||||||
- Provide concrete examples
|
1. Overview - What & why
|
||||||
- Show real-world usage
|
2. Core concepts - Building blocks
|
||||||
- Include code snippets
|
3. Deep dive - How it works
|
||||||
- Demonstrate best practices
|
4. Examples - Practical usage
|
||||||
|
5. Gotchas - Common pitfalls
|
||||||
|
6. Resources - Further learning
|
||||||
|
|
||||||
**4. Advanced Concepts:**
|
Techniques:
|
||||||
- Cover edge cases and gotchas
|
- Analogies for complex concepts
|
||||||
- Explain performance implications
|
- Progressive complexity
|
||||||
- Discuss alternatives and trade-offs
|
- Interactive examples
|
||||||
- Address common misconceptions
|
- Visual representations
|
||||||
|
- Real-world scenarios
|
||||||
## Content Types
|
|
||||||
|
|
||||||
**Technical Concepts:**
|
|
||||||
- Explain "what" before "how"
|
|
||||||
- Connect to familiar concepts
|
|
||||||
- Build understanding incrementally
|
|
||||||
- Use analogies and metaphors
|
|
||||||
- Address common misconceptions
|
|
||||||
|
|
||||||
**Code Explanations:**
|
|
||||||
- Walk through logic step by step
|
|
||||||
- Explain design decisions and rationale
|
|
||||||
- Highlight important patterns
|
|
||||||
- Point out potential pitfalls
|
|
||||||
- Show alternative approaches
|
|
||||||
|
|
||||||
**System Architecture:**
|
|
||||||
- Start with overall design
|
|
||||||
- Explain component interactions
|
|
||||||
- Show data flow and processes
|
|
||||||
- Discuss scalability and performance
|
|
||||||
- Cover security considerations
|
|
||||||
|
|
||||||
**Framework/Library Usage:**
|
|
||||||
- Explain core concepts first
|
|
||||||
- Show common usage patterns
|
|
||||||
- Provide working examples
|
|
||||||
- Explain configuration options
|
|
||||||
- Cover troubleshooting tips
|
|
||||||
|
|
||||||
## Visual Aids (--visual)
|
|
||||||
|
|
||||||
**Diagram Types:**
|
|
||||||
- **Mermaid Diagrams**: Flowcharts, sequence diagrams, class diagrams
|
|
||||||
- **ASCII Art**: Simple visualizations and layouts
|
|
||||||
- **Process Flows**: Step-by-step workflow diagrams
|
|
||||||
- **Architecture Diagrams**: System component relationships
|
|
||||||
|
|
||||||
**When to Use Visuals:**
|
|
||||||
- Complex processes or workflows
|
|
||||||
- System architecture explanations
|
|
||||||
- Data flow and transformations
|
|
||||||
- Relationship mapping
|
|
||||||
- Timeline or sequence explanations
|
|
||||||
|
|
||||||
## Research Requirements
|
|
||||||
|
|
||||||
**Authoritative Sources:**
|
|
||||||
- Official documentation via `--c7`
|
|
||||||
- Framework guides and best practices
|
|
||||||
- Industry standards and specifications
|
|
||||||
- Expert opinions and case studies
|
|
||||||
|
|
||||||
**Verification Standards:**
|
|
||||||
- Never explain without verification
|
|
||||||
- Always cite authoritative sources
|
|
||||||
- Test code examples before including
|
|
||||||
- Validate against current versions
|
|
||||||
- Include source references in explanations
|
|
||||||
|
|
||||||
## UltraCompressed Mode (--uc)
|
|
||||||
|
|
||||||
**Compression Rules:**
|
|
||||||
- ~70% token reduction from standard explanations
|
|
||||||
- Generate legend for symbols/abbreviations
|
|
||||||
- Use telegram-style formatting
|
|
||||||
- Structure: lists > paragraphs, tables > prose
|
|
||||||
- Remove articles, conjunctions, fillers
|
|
||||||
- Focus on essential information only
|
|
||||||
|
|
||||||
**Example Transformation:**
|
|
||||||
- Standard: "The function takes three parameters and returns a boolean value"
|
|
||||||
- Compressed: "fn takes 3 params→bool"
|
|
||||||
|
|
||||||
## Deliverables
|
|
||||||
- **Clear Explanations**: Appropriate depth level with structured content
|
|
||||||
- **Working Examples**: Tested, runnable code snippets
|
|
||||||
- **Visual Aids**: Diagrams, charts, and illustrations (if requested)
|
|
||||||
- **Learning Resources**: Curated resources for further study
|
|
||||||
- **Source References**: Comprehensive citations and links
|
|
||||||
|
|
||||||
## Output Locations
|
|
||||||
- **Explanations**: `.claudedocs/summaries/explanation-{topic}-{timestamp}.md`
|
|
||||||
- **Learning Resources**: `.claudedocs/reports/learning-resources-{timestamp}.md`
|
|
||||||
- **Code Examples**: Embedded in explanation files
|
|
||||||
|
|
||||||
## Research Requirements
|
|
||||||
External_Library_Research:
|
|
||||||
- Identify library/framework mentioned
|
|
||||||
- Context7 lookup for official documentation
|
|
||||||
- Verify API patterns and examples
|
|
||||||
- Check version compatibility
|
|
||||||
- Document findings in implementation
|
|
||||||
Pattern_Research:
|
|
||||||
- Search existing codebase for similar patterns
|
|
||||||
- Magic component search if UI-related
|
|
||||||
- WebSearch for official documentation
|
|
||||||
- Validate approach with Sequential thinking
|
|
||||||
- Document pattern choice rationale
|
|
||||||
API_Integration_Research:
|
|
||||||
- Official documentation lookup
|
|
||||||
- Authentication requirements
|
|
||||||
- Rate limiting and error handling
|
|
||||||
- SDK availability and examples
|
|
||||||
- Integration testing approach
|
|
||||||
|
|
||||||
## Report Notifications
|
|
||||||
📄 Analysis report saved to: {path}
|
|
||||||
📊 Metrics updated: {path}
|
|
||||||
📋 Summary saved to: {path}
|
|
||||||
💾 Checkpoint created: {path}
|
|
||||||
📚 Documentation created: {path}
|
|
||||||
📁 Created directory: {path}
|
|
||||||
✅ {operation} completed successfully
|
|
||||||
❌ {operation} failed: {reason}
|
|
||||||
⚠ {operation} completed w/ warnings
|
|
||||||
|
|
||||||
## Best Practices
|
## Best Practices
|
||||||
|
|
||||||
**Effective Explanations:**
|
Clarity:
|
||||||
- Start simple, build complexity gradually
|
- Define terms before use
|
||||||
- Use concrete examples and analogies
|
- Build on prior knowledge
|
||||||
- Address the audience's experience level
|
- Use consistent terminology
|
||||||
- Anticipate and answer common questions
|
- Provide context
|
||||||
- Provide multiple perspectives when helpful
|
- Summarize key points
|
||||||
|
|
||||||
**Quality Standards:**
|
Engagement:
|
||||||
- Verify all technical information
|
- Start with "why it matters"
|
||||||
- Test all code examples
|
- Use relatable examples
|
||||||
- Keep explanations current and accurate
|
- Address common questions
|
||||||
- Use clear, precise language
|
- Provide hands-on exercises
|
||||||
- Structure content logically
|
- Link to resources
|
||||||
|
|
||||||
## Troubleshooting
|
## Examples
|
||||||
- **Complex Topics**: Use `--seq --think-hard` for step-by-step breakdown
|
|
||||||
- **Framework Questions**: Combine `--c7 --examples` for comprehensive coverage
|
|
||||||
- **Beginner Audiences**: Use `--depth eli5 --visual --examples`
|
|
||||||
- **Expert Deep Dives**: Apply `--depth expert --comprehensive --ultrathink`
|
|
||||||
|
|
||||||
## Success Messages
|
```bash
|
||||||
✅ {operation} completed successfully
|
# Explain React hooks for beginners
|
||||||
📝 Created: {file_path}
|
/explain --depth beginner --style tutorial "React hooks"
|
||||||
✏ Updated: {file_path}
|
|
||||||
✨ Task completed: {task_title}
|
# Deep dive into database indexing
|
||||||
|
/explain --depth advanced --visual "B-tree indexes"
|
||||||
|
|
||||||
|
# System architecture explanation
|
||||||
|
/explain --style reference --visual "microservices communication"
|
||||||
|
|
||||||
|
# Algorithm explanation with complexity
|
||||||
|
/explain --depth expert --think "quicksort optimization"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Deliverables
|
||||||
|
|
||||||
|
- Comprehensive explanation document
|
||||||
|
- Code examples & snippets
|
||||||
|
- Visual diagrams if requested
|
||||||
|
- Practice exercises
|
||||||
|
- Resource links & references
|
||||||
|
- Summary & key takeaways
|
||||||
@@ -1,38 +1,7 @@
|
|||||||
# /git - Manage git workflows and repository operations
|
# /git - Manage git workflows and repository operations
|
||||||
|
|
||||||
## Legend
|
## Legend
|
||||||
| Symbol | Meaning | | Abbrev | Meaning |
|
@include shared/universal-constants.yml#Universal_Legend
|
||||||
|--------|---------|---|--------|---------|
|
|
||||||
| → | leads to | | cfg | configuration |
|
|
||||||
| & | and/with | | impl | implementation |
|
|
||||||
| w/ | with | | perf | performance |
|
|
||||||
| @ | at/located | | ops | operations |
|
|
||||||
| > | greater than | | val | validation |
|
|
||||||
| ∀ | for all/every | | req | requirements |
|
|
||||||
| ∃ | exists/there is | | deps | dependencies |
|
|
||||||
| ∴ | therefore | | env | environment |
|
|
||||||
| ∵ | because | | db | database |
|
|
||||||
| ≡ | equivalent | | api | interface |
|
|
||||||
| ≈ | approximately | | docs | documentation |
|
|
||||||
| 📁 | directory/path | | std | standard |
|
|
||||||
| 🔢 | number/count | | def | default |
|
|
||||||
| 📝 | text/string | | ctx | context |
|
|
||||||
| ⚙ | setting/config | | err | error |
|
|
||||||
| 🎛 | control/flags | | exec | execution |
|
|
||||||
| 🔧 | configuration | | qual | quality |
|
|
||||||
| 📋 | group/category | | rec | recovery |
|
|
||||||
| 🚨 | critical/urgent | | sev | severity |
|
|
||||||
| ⚠ | warning/caution | | resp | response |
|
|
||||||
| 🔄 | retry/recovery | | esc | escalation |
|
|
||||||
| ✅ | success/fixed | | tok | token |
|
|
||||||
| ❌ | failure/error | | opt | optimization |
|
|
||||||
| ℹ | information | | UX | user experience |
|
|
||||||
| ⚡ | fast/quick | | UI | user interface |
|
|
||||||
| 🐌 | slow/delayed | | C | critical |
|
|
||||||
| ✨ | complete/done | | H | high |
|
|
||||||
| 📖 | read operation | | M | medium |
|
|
||||||
| ✏ | edit operation | | L | low |
|
|
||||||
| 🗑 | delete operation | | |
|
|
||||||
|
|
||||||
## Purpose
|
## Purpose
|
||||||
Manage comprehensive git workflows for repositories specified in $ARGUMENTS with safety checks and automation.
|
Manage comprehensive git workflows for repositories specified in $ARGUMENTS with safety checks and automation.
|
||||||
@@ -40,221 +9,132 @@ Manage comprehensive git workflows for repositories specified in $ARGUMENTS with
|
|||||||
## Syntax
|
## Syntax
|
||||||
`/git [flags] [operation/message]`
|
`/git [flags] [operation/message]`
|
||||||
|
|
||||||
## Universal Flags
|
@include shared/flag-inheritance.yml#Universal_Always
|
||||||
--plan: "Show execution plan before running"
|
|
||||||
--uc: "UltraCompressed mode (~70% token reduction)"
|
|
||||||
--ultracompressed: "Alias for --uc"
|
|
||||||
--think: "Multi-file analysis w/ context (4K tokens)"
|
|
||||||
--think-hard: "Deep architectural analysis (10K tokens)"
|
|
||||||
--ultrathink: "Critical system redesign (32K tokens)"
|
|
||||||
--c7: "Enable Context7→library documentation lookup"
|
|
||||||
--seq: "Enable Sequential→complex analysis & thinking"
|
|
||||||
--magic: "Enable Magic→UI component generation"
|
|
||||||
--pup: "Enable Puppeteer→browser automation & testing"
|
|
||||||
--all-mcp: "Enable all MCP servers"
|
|
||||||
--no-mcp: "Disable all MCP servers (native tools only)"
|
|
||||||
--no-c7: "Disable Context7 specifically"
|
|
||||||
--no-seq: "Disable Sequential thinking specifically"
|
|
||||||
--no-magic: "Disable Magic UI builder specifically"
|
|
||||||
--no-pup: "Disable Puppeteer specifically"
|
|
||||||
## Execution Control
|
|
||||||
--watch: "Continuous monitoring w/ real-time feedback"
|
|
||||||
--interactive: "Step-by-step guided process w/ user control"
|
|
||||||
--dry-run: "Preview changes without execution"
|
|
||||||
--force: "Override safety checks & confirmations"
|
|
||||||
|
|
||||||
## Command-Specific Flags
|
## Core Operations
|
||||||
|
|
||||||
**Core Operations:**
|
--commit flag:
|
||||||
- `--status`: Comprehensive repository status with branch and remote information
|
- Stage appropriate files
|
||||||
- `--commit [message]`: Create commit with automated staging and validation
|
- Generate meaningful commit message
|
||||||
- `--branch [name]`: Create, switch, or manage branches
|
- Include co-author attribution
|
||||||
- `--sync`: Fetch, pull, and push with conflict resolution
|
- Follow conventional commits
|
||||||
- `--merge [branch]`: Merge branches with conflict analysis
|
|
||||||
- `--stash [message]`: Stash management with descriptive messages
|
|
||||||
|
|
||||||
**Advanced Operations:**
|
--pr flag:
|
||||||
- `--history`: Detailed commit history with filtering options
|
- Create pull request
|
||||||
- `--checkpoint [message]`: Create tagged state snapshots for rollback
|
- Generate PR description
|
||||||
- `--rollback [checkpoint]`: Rollback to specific checkpoint safely
|
- Set reviewers & labels
|
||||||
- `--rebase [branch]`: Interactive or automatic rebase operations
|
- Link related issues
|
||||||
|
|
||||||
**Branch Management:**
|
--flow flag:
|
||||||
- `--list`: Show all branches with descriptions and status
|
- feature: Feature branch workflow
|
||||||
- `--delete [branch]`: Delete merged branches safely
|
- hotfix: Emergency fix workflow
|
||||||
- `--track [remote/branch]`: Set up branch tracking
|
- release: Release branch workflow
|
||||||
|
- gitflow: Full GitFlow model
|
||||||
|
|
||||||
**Safety & Validation:**
|
## Git Workflows
|
||||||
- `--verify`: Verify repository state and integrity
|
|
||||||
- `--cleanup`: Clean up stale branches and references
|
Feature Development:
|
||||||
- `--backup`: Create backup before risky operations
|
```bash
|
||||||
|
# Start new feature
|
||||||
|
/git --flow feature "user-authentication"
|
||||||
|
|
||||||
|
# Commit progress
|
||||||
|
/git --commit "Add login form validation"
|
||||||
|
|
||||||
|
# Create PR when ready
|
||||||
|
/git --pr --reviewers @team
|
||||||
|
```
|
||||||
|
|
||||||
|
Hotfix Process:
|
||||||
|
```bash
|
||||||
|
# Emergency fix
|
||||||
|
/git --flow hotfix "security-patch"
|
||||||
|
|
||||||
|
# Quick commit & PR
|
||||||
|
/git --commit --pr "Fix SQL injection vulnerability"
|
||||||
|
```
|
||||||
|
|
||||||
|
Release Management:
|
||||||
|
```bash
|
||||||
|
# Start release
|
||||||
|
/git --flow release "v2.0.0"
|
||||||
|
|
||||||
|
# Tag & merge
|
||||||
|
/git --tag --merge "Release version 2.0.0"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Safety Features
|
||||||
|
|
||||||
|
Pre-commit Checks:
|
||||||
|
- Verify branch is up to date
|
||||||
|
- Run linters & formatters
|
||||||
|
- Execute test suite
|
||||||
|
- Check for secrets
|
||||||
|
- Validate commit message
|
||||||
|
|
||||||
|
Merge Protection:
|
||||||
|
- Require PR reviews
|
||||||
|
- Ensure CI passes
|
||||||
|
- Check branch policies
|
||||||
|
- Prevent force pushes
|
||||||
|
- Backup before risky ops
|
||||||
|
|
||||||
|
## Advanced Features
|
||||||
|
|
||||||
|
--interactive flag:
|
||||||
|
- Interactive staging (git add -p)
|
||||||
|
- Commit message editor
|
||||||
|
- Conflict resolution helper
|
||||||
|
- Cherry-pick assistance
|
||||||
|
|
||||||
|
--history flag:
|
||||||
|
- Clean up commit history
|
||||||
|
- Interactive rebase
|
||||||
|
- Squash related commits
|
||||||
|
- Reorder for clarity
|
||||||
|
|
||||||
|
--stats flag:
|
||||||
|
- Contribution analytics
|
||||||
|
- Code churn metrics
|
||||||
|
- Review turnaround time
|
||||||
|
- Branch lifetime stats
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
Commits:
|
||||||
|
- Atomic, focused changes
|
||||||
|
- Present tense messages
|
||||||
|
- Reference issue numbers
|
||||||
|
- Co-author attribution
|
||||||
|
- Sign commits when required
|
||||||
|
|
||||||
|
Branches:
|
||||||
|
- Descriptive names
|
||||||
|
- Regular rebasing
|
||||||
|
- Clean before merging
|
||||||
|
- Delete after merge
|
||||||
|
- Protect main branches
|
||||||
|
|
||||||
## Examples
|
## Examples
|
||||||
- `/git --status` → Comprehensive repository status
|
|
||||||
- `/git --commit "Add authentication feature"` → Create commit with message
|
|
||||||
- `/git --branch feature/ui-redesign` → Create and switch to branch
|
|
||||||
- `/git --sync --verify` → Sync with remote and verify state
|
|
||||||
- `/git --merge develop --think` → Merge with conflict analysis
|
|
||||||
- `/git --checkpoint "Before major refactor"` → Create safety checkpoint
|
|
||||||
- `/git --history --author "john" --since "2024-01-01"` → Filtered history
|
|
||||||
|
|
||||||
## Git Operations
|
```bash
|
||||||
|
# Standard commit with message
|
||||||
|
/git --commit "Add user profile API endpoint"
|
||||||
|
|
||||||
**Status Operation (--status):**
|
# Create PR with reviewers
|
||||||
- Working tree status and staged changes
|
/git --pr --reviewers alice,bob --labels api,feature
|
||||||
- Current branch and upstream tracking
|
|
||||||
- Stashed changes with timestamps
|
|
||||||
- Recent commits (last 5) with summaries
|
|
||||||
- Unpushed commits count
|
|
||||||
- Remote repository status
|
|
||||||
|
|
||||||
**Commit Operation (--commit):**
|
# Interactive cleanup before PR
|
||||||
- Automatic staging of modified files
|
/git --history --interactive
|
||||||
- Generate conventional commit message if missing
|
|
||||||
- Pre-commit hooks and validation
|
|
||||||
- Test verification before commit
|
|
||||||
- Create automatic checkpoint
|
|
||||||
- GPG signing if configured
|
|
||||||
|
|
||||||
**Branch Management (--branch):**
|
# Full feature workflow
|
||||||
- Create new branch from HEAD or specified base
|
/git --flow feature "payment-integration" --think
|
||||||
- Switch to existing branch with safety checks
|
```
|
||||||
- Delete merged branches with verification
|
|
||||||
- List all branches with descriptions
|
|
||||||
- Automatic remote tracking setup
|
|
||||||
- Protection for main/master branches
|
|
||||||
|
|
||||||
**Sync Operations (--sync):**
|
|
||||||
- Fetch from all configured remotes
|
|
||||||
- Pull with rebase to maintain clean history
|
|
||||||
- Push to tracked remote branch
|
|
||||||
- Handle authentication automatically
|
|
||||||
- Resolve merge conflicts interactively
|
|
||||||
- Update submodules if present
|
|
||||||
|
|
||||||
**Merge Operations (--merge):**
|
|
||||||
- Fetch target branch before merging
|
|
||||||
- Analyze potential conflicts
|
|
||||||
- Create checkpoint before merge
|
|
||||||
- Use appropriate merge strategy
|
|
||||||
- Handle conflicts with interactive resolution
|
|
||||||
- Verify merge results
|
|
||||||
|
|
||||||
**Stash Management (--stash):**
|
|
||||||
- Save changes with descriptive message
|
|
||||||
- List stashes with timestamps and summaries
|
|
||||||
- Apply or pop specific stash entries
|
|
||||||
- Drop old or unnecessary stashes
|
|
||||||
- Handle conflicts during stash application
|
|
||||||
|
|
||||||
**History Operations (--history):**
|
|
||||||
- Formatted commit log with customizable output
|
|
||||||
- Filter by author, date, or file path
|
|
||||||
- Branch topology visualization
|
|
||||||
- Search commit messages
|
|
||||||
- File change statistics
|
|
||||||
|
|
||||||
**Checkpoint System (--checkpoint):**
|
|
||||||
- Create tagged state snapshots
|
|
||||||
- Store with descriptive messages
|
|
||||||
- Maintain checkpoint manifest
|
|
||||||
- Enable safe rollback operations
|
|
||||||
- Track checkpoint metadata
|
|
||||||
|
|
||||||
**Rollback Operations (--rollback):**
|
|
||||||
- List available checkpoints with details
|
|
||||||
- Verify rollback safety
|
|
||||||
- Create pre-rollback checkpoint
|
|
||||||
- Execute rollback with validation
|
|
||||||
- Verify final repository state
|
|
||||||
|
|
||||||
## Workflow Patterns
|
|
||||||
|
|
||||||
**Standard Development Workflow:**
|
|
||||||
1. Check status → Understand current state
|
|
||||||
2. Create checkpoint → Safety backup
|
|
||||||
3. Execute operation → Perform git action
|
|
||||||
4. Verify results → Validate changes
|
|
||||||
5. Sync with remote → Update shared repository
|
|
||||||
|
|
||||||
**Feature Development:**
|
|
||||||
1. `git --status` → Check current state
|
|
||||||
2. `git --branch feature/new-feature` → Create feature branch
|
|
||||||
3. Development work...
|
|
||||||
4. `git --commit "Implement feature"` → Commit changes
|
|
||||||
5. `git --sync` → Push to remote
|
|
||||||
6. `git --merge main` → Integrate with main
|
|
||||||
|
|
||||||
**Safe Operations:**
|
|
||||||
- Always create checkpoints before risky operations
|
|
||||||
- Verify repository state after major changes
|
|
||||||
- Use interactive mode for conflict resolution
|
|
||||||
- Maintain clean commit history with conventional messages
|
|
||||||
|
|
||||||
## Deliverables
|
## Deliverables
|
||||||
- **Updated Repository State**: Clean, consistent git history
|
|
||||||
- **Branch Management**: Organized branch structure
|
|
||||||
- **Remote Synchronization**: Up-to-date remote repositories
|
|
||||||
- **Audit Trail**: Complete history of operations
|
|
||||||
- **Safety Checkpoints**: Rollback points for recovery
|
|
||||||
|
|
||||||
## Research Requirements
|
|
||||||
External_Library_Research:
|
|
||||||
- Identify library/framework mentioned
|
|
||||||
- Context7 lookup for official documentation
|
|
||||||
- Verify API patterns and examples
|
|
||||||
- Check version compatibility
|
|
||||||
- Document findings in implementation
|
|
||||||
Pattern_Research:
|
|
||||||
- Search existing codebase for similar patterns
|
|
||||||
- Magic component search if UI-related
|
|
||||||
- WebSearch for official documentation
|
|
||||||
- Validate approach with Sequential thinking
|
|
||||||
- Document pattern choice rationale
|
|
||||||
API_Integration_Research:
|
|
||||||
- Official documentation lookup
|
|
||||||
- Authentication requirements
|
|
||||||
- Rate limiting and error handling
|
|
||||||
- SDK availability and examples
|
|
||||||
- Integration testing approach
|
|
||||||
|
|
||||||
## Lifecycle
|
|
||||||
Pre_Execution:
|
|
||||||
Risk_Assessment: Calculate risk score 1-10 based on data loss potential, irreversibility, scope, security
|
|
||||||
Environment_Validation: Check required tools, permissions, resources, dependencies
|
|
||||||
State_Preparation: Create checkpoint before risky ops, cache previous results
|
|
||||||
During_Execution:
|
|
||||||
Progress_Monitoring: Track operation progress, resource usage, error rates, token consumption
|
|
||||||
Dynamic_Optimization: Adjust parallelism, switch strategies, cache results, fallback to native
|
|
||||||
Error_Handling: Detect errors immediately, classify transient vs permanent, retry/fallback/halt
|
|
||||||
Post_Execution:
|
|
||||||
Verification: Confirm expected outcomes achieved, no side effects, state consistent
|
|
||||||
Cleanup: Remove temp files, locks, cached data; update audit logs, metrics, docs
|
|
||||||
Reporting: Generate success/failure report, performance metrics, recommendations
|
|
||||||
|
|
||||||
## Integration Patterns
|
|
||||||
|
|
||||||
**Quality Assurance:**
|
|
||||||
- Pre-commit hooks for code quality
|
|
||||||
- Test verification before commits
|
|
||||||
- Conventional commit message enforcement
|
|
||||||
- Branch protection rules
|
|
||||||
|
|
||||||
**Team Collaboration:**
|
|
||||||
- Consistent branching strategies
|
|
||||||
- Merge request workflows
|
|
||||||
- Code review integration
|
|
||||||
- Conflict resolution procedures
|
|
||||||
|
|
||||||
## Troubleshooting
|
|
||||||
- **Merge Conflicts**: Use `--merge --interactive` for guided resolution
|
|
||||||
- **Complex History**: Apply `--history --visual` for topology understanding
|
|
||||||
- **Repository Issues**: Use `--verify --cleanup` for maintenance
|
|
||||||
- **Rollback Needs**: Apply `--rollback` with checkpoint selection
|
|
||||||
|
|
||||||
## Success Messages
|
|
||||||
✅ {operation} completed successfully
|
|
||||||
📝 Created: {file_path}
|
|
||||||
✏ Updated: {file_path}
|
|
||||||
✨ Task completed: {task_title}
|
|
||||||
|
|
||||||
|
- Clean git history
|
||||||
|
- Meaningful commit messages
|
||||||
|
- Automated PR creation
|
||||||
|
- Branch management
|
||||||
|
- Workflow documentation
|
||||||
@@ -1,329 +1,58 @@
|
|||||||
# /improve - Enhance code quality, performance and architecture
|
# /improve - Enhance code quality, performance and architecture
|
||||||
|
|
||||||
## Legend
|
@include shared/universal-constants.yml#Universal_Legend
|
||||||
| Symbol | Meaning | | Abbrev | Meaning |
|
|
||||||
|--------|---------|---|--------|---------|
|
|
||||||
| → | leads to | | cfg | configuration |
|
|
||||||
| & | and/with | | impl | implementation |
|
|
||||||
| w/ | with | | perf | performance |
|
|
||||||
| @ | at/located | | ops | operations |
|
|
||||||
| > | greater than | | val | validation |
|
|
||||||
| ∀ | for all/every | | req | requirements |
|
|
||||||
| ∃ | exists/there is | | deps | dependencies |
|
|
||||||
| ∴ | therefore | | env | environment |
|
|
||||||
| ∵ | because | | db | database |
|
|
||||||
| ≡ | equivalent | | api | interface |
|
|
||||||
| ≈ | approximately | | docs | documentation |
|
|
||||||
| 📁 | directory/path | | std | standard |
|
|
||||||
| 🔢 | number/count | | def | default |
|
|
||||||
| 📝 | text/string | | ctx | context |
|
|
||||||
| ⚙ | setting/config | | err | error |
|
|
||||||
| 🎛 | control/flags | | exec | execution |
|
|
||||||
| 🔧 | configuration | | qual | quality |
|
|
||||||
| 📋 | group/category | | rec | recovery |
|
|
||||||
| 🚨 | critical/urgent | | sev | severity |
|
|
||||||
| ⚠ | warning/caution | | resp | response |
|
|
||||||
| 🔄 | retry/recovery | | esc | escalation |
|
|
||||||
| ✅ | success/fixed | | tok | token |
|
|
||||||
| ❌ | failure/error | | opt | optimization |
|
|
||||||
| ℹ | information | | UX | user experience |
|
|
||||||
| ⚡ | fast/quick | | UI | user interface |
|
|
||||||
| 🐌 | slow/delayed | | C | critical |
|
|
||||||
| ✨ | complete/done | | H | high |
|
|
||||||
| 📖 | read operation | | M | medium |
|
|
||||||
| ✏ | edit operation | | L | low |
|
|
||||||
| 🗑 | delete operation | | |
|
|
||||||
|
|
||||||
## Purpose
|
## Purpose
|
||||||
Enhance code quality, performance, and architecture for systems specified in $ARGUMENTS using systematic improvement methodologies.
|
Systematically improve code quality, performance, and architecture in $ARGUMENTS using best practices and optimization techniques.
|
||||||
|
|
||||||
## Syntax
|
## Syntax
|
||||||
`/improve [flags] [target]`
|
`/improve [flags] [target]`
|
||||||
|
|
||||||
## Universal Flags
|
@include shared/flag-inheritance.yml#Universal_Always
|
||||||
--plan: "Show execution plan before running"
|
|
||||||
--uc: "UltraCompressed mode (~70% token reduction)"
|
Examples:
|
||||||
--ultracompressed: "Alias for --uc"
|
- `/improve --quality` - Code quality improvements
|
||||||
--think: "Multi-file analysis w/ context (4K tokens)"
|
- `/improve --perf --iterate` - Performance optimization
|
||||||
--think-hard: "Deep architectural analysis (10K tokens)"
|
- `/improve --arch --think-hard` - Architecture refactoring
|
||||||
--ultrathink: "Critical system redesign (32K tokens)"
|
|
||||||
--c7: "Enable Context7→library documentation lookup"
|
|
||||||
--seq: "Enable Sequential→complex analysis & thinking"
|
|
||||||
--magic: "Enable Magic→UI component generation"
|
|
||||||
--pup: "Enable Puppeteer→browser automation & testing"
|
|
||||||
--all-mcp: "Enable all MCP servers"
|
|
||||||
--no-mcp: "Disable all MCP servers (native tools only)"
|
|
||||||
--no-c7: "Disable Context7 specifically"
|
|
||||||
--no-seq: "Disable Sequential thinking specifically"
|
|
||||||
--no-magic: "Disable Magic UI builder specifically"
|
|
||||||
--no-pup: "Disable Puppeteer specifically"
|
|
||||||
|
|
||||||
## Command-Specific Flags
|
## Command-Specific Flags
|
||||||
|
--quality: "Code quality improvements (readability, maintainability, DRY)"
|
||||||
|
--perf: "Performance optimizations (algorithms, caching, queries)"
|
||||||
|
--arch: "Architecture improvements (patterns, coupling, scalability)"
|
||||||
|
--refactor: "Safe refactoring preserving behavior"
|
||||||
|
--iterate: "Iterative improvement until threshold met"
|
||||||
|
--threshold: "Quality threshold (low|medium|high|perfect)"
|
||||||
|
--metrics: "Show before/after metrics"
|
||||||
|
--safe: "Conservative mode - only safe changes"
|
||||||
|
|
||||||
**Improvement Focus:**
|
## Improvement Categories
|
||||||
- `--quality`: Code structure, maintainability, and clean code principles
|
|
||||||
- `--performance`: System performance, bottlenecks, and optimization
|
|
||||||
- `--security`: Security improvements and vulnerability fixes
|
|
||||||
- `--architecture`: System design and architectural improvements
|
|
||||||
- `--ux`: User experience and interface improvements
|
|
||||||
|
|
||||||
**Quality Enhancements:**
|
**Code Quality:** Naming clarity | Function extraction | Duplication removal | Complexity reduction | Error handling | Type safety
|
||||||
- `--solid`: Apply SOLID principles systematically
|
|
||||||
- `--refactor`: Clean code refactoring with modern patterns
|
|
||||||
- `--metrics`: Generate comprehensive quality metrics
|
|
||||||
- `--coverage`: Improve test coverage and quality
|
|
||||||
|
|
||||||
**Performance Optimization:**
|
**Performance:** Algorithm optimization | Query optimization | Caching strategies | Lazy loading | Memory efficiency | Parallel processing
|
||||||
- `--profile`: Performance profiling and bottleneck analysis
|
|
||||||
- `--cache`: Implement caching strategies
|
|
||||||
- `--async`: Optimize for asynchronous operations
|
|
||||||
- `--database`: Database query and schema optimization
|
|
||||||
|
|
||||||
**Execution Modes:**
|
**Architecture:** Design patterns | Dependency injection | Layer separation | Module boundaries | API design | Scalability patterns
|
||||||
- `--iterate`: Iterative improvement until threshold reached
|
|
||||||
- `--threshold [percent]`: Set target improvement percentage (default 85%)
|
|
||||||
- `--watch`: Continuous improvement monitoring
|
|
||||||
- `--interactive`: Guided improvement with user choices
|
|
||||||
|
|
||||||
## Examples
|
**Maintainability:** Documentation | Test coverage | Configuration extraction | Magic number removal | Dead code elimination
|
||||||
- `/improve --quality --solid --metrics` → Code quality with SOLID principles
|
|
||||||
- `/improve --performance --profile --cache` → Performance optimization with caching
|
|
||||||
- `/improve --iterate --threshold 90 --interactive` → Iterative improvement to 90%
|
|
||||||
- `/improve --security --architecture --seq` → Security and architecture analysis
|
|
||||||
- `/improve --ux --performance --watch` → UX and performance with monitoring
|
|
||||||
|
|
||||||
## Code Quality Mode (--quality)
|
## Improvement Process
|
||||||
|
|
||||||
**SOLID Principles Application:**
|
**1. Analysis:** Current state assessment | Identify improvement areas | Prioritize by impact | Set measurable goals
|
||||||
- **Single Responsibility**: One class, one clear purpose
|
|
||||||
- **Open/Closed**: Extensible without modification
|
|
||||||
- **Liskov Substitution**: Subtypes must be substitutable
|
|
||||||
- **Interface Segregation**: Specific over general interfaces
|
|
||||||
- **Dependency Inversion**: Depend on abstractions, not concretions
|
|
||||||
|
|
||||||
**Refactoring Techniques:**
|
**2. Planning:** Safe refactoring path | Preserve functionality | Incremental changes | Rollback strategy
|
||||||
- Extract methods and classes for complex logic
|
|
||||||
- Inline unnecessary abstractions
|
|
||||||
- Rename variables and functions for clarity
|
|
||||||
- Move code to appropriate modules
|
|
||||||
- Remove duplication (DRY principle)
|
|
||||||
- Simplify conditionals and loops
|
|
||||||
- Reduce coupling, increase cohesion
|
|
||||||
|
|
||||||
**Quality Metrics Tracking:**
|
**3. Implementation:** Small atomic changes | Continuous testing | Performance monitoring | Code review ready
|
||||||
- Cyclomatic complexity (target < 5)
|
|
||||||
- Method/function length (target < 20 lines)
|
|
||||||
- Class cohesion and coupling metrics
|
|
||||||
- Code duplication percentage
|
|
||||||
- Test coverage (target > 80%)
|
|
||||||
- Documentation completeness
|
|
||||||
- Technical debt assessment
|
|
||||||
|
|
||||||
**Clean Code Principles:**
|
**4. Validation:** Behavior preservation | Performance gains | Quality metrics | Regression testing
|
||||||
- Meaningful, self-documenting names
|
|
||||||
- Functions that do one thing well
|
|
||||||
- Consistent coding style and formatting
|
|
||||||
- Proper error handling and logging
|
|
||||||
- Elimination of magic numbers and strings
|
|
||||||
- Comments that explain why, not what
|
|
||||||
|
|
||||||
## Performance Mode (--performance)
|
@include shared/quality-patterns.yml#Code_Quality_Metrics
|
||||||
|
|
||||||
**Code Optimization:**
|
|
||||||
- Algorithm complexity reduction (O(n²) → O(n log n))
|
|
||||||
- Efficient data structures selection
|
|
||||||
- Caching frequently accessed data
|
|
||||||
- Lazy loading and pagination strategies
|
|
||||||
- Asynchronous and parallel processing
|
|
||||||
- Memory usage optimization
|
|
||||||
|
|
||||||
**Database Optimization:**
|
|
||||||
- Query optimization and proper indexing
|
|
||||||
- N+1 query elimination
|
|
||||||
- Connection pooling implementation
|
|
||||||
- Batch operations for bulk updates
|
|
||||||
- Strategic denormalization
|
|
||||||
- Query result caching
|
|
||||||
|
|
||||||
**Frontend Optimization:**
|
|
||||||
- Bundle size reduction and tree shaking
|
|
||||||
- Code splitting and lazy loading
|
|
||||||
- Image and asset optimization
|
|
||||||
- Render performance improvements
|
|
||||||
- Service worker caching strategies
|
|
||||||
- React/Vue re-render optimization
|
|
||||||
|
|
||||||
**System Optimization:**
|
|
||||||
- Load balancing strategies
|
|
||||||
- CDN implementation and optimization
|
|
||||||
- Compression (gzip/brotli)
|
|
||||||
- HTTP/2 and proper caching headers
|
|
||||||
- Resource pooling and connection management
|
|
||||||
- Microservice communication optimization
|
|
||||||
|
|
||||||
## Iterative Mode (--iterate)
|
|
||||||
|
|
||||||
**Improvement Process:**
|
|
||||||
|
|
||||||
**1. Baseline Measurement:**
|
|
||||||
- Current performance metrics
|
|
||||||
- Code quality scores
|
|
||||||
- Test coverage percentage
|
|
||||||
- User experience metrics
|
|
||||||
- System reliability indicators
|
|
||||||
|
|
||||||
**2. Targeted Improvements:**
|
|
||||||
- Identify highest impact areas (80/20 rule)
|
|
||||||
- Prioritize improvements by ROI
|
|
||||||
- Make incremental, measurable changes
|
|
||||||
- Maintain working state throughout
|
|
||||||
|
|
||||||
**3. Progress Tracking:**
|
|
||||||
- Measure improvement after each iteration
|
|
||||||
- Document changes and their impact
|
|
||||||
- Calculate return on investment
|
|
||||||
- Adjust strategy based on results
|
|
||||||
|
|
||||||
**4. Completion Criteria:**
|
|
||||||
- Target threshold achievement
|
|
||||||
- Diminishing returns detection
|
|
||||||
- Time or budget constraints
|
|
||||||
- "Good enough" quality level
|
|
||||||
|
|
||||||
**Focus Areas by Type:**
|
|
||||||
- **Quality**: Complexity reduction, duplication removal, coverage increase
|
|
||||||
- **Performance**: Response time, throughput, resource utilization
|
|
||||||
- **User Experience**: Load time, responsiveness, error reduction
|
|
||||||
- **Maintainability**: Documentation, test quality, code structure
|
|
||||||
|
|
||||||
## Architecture Improvements (--architecture)
|
|
||||||
|
|
||||||
**Design Patterns:**
|
|
||||||
- Apply appropriate design patterns
|
|
||||||
- Implement dependency injection
|
|
||||||
- Use domain-driven design principles
|
|
||||||
- Implement proper separation of concerns
|
|
||||||
|
|
||||||
**System Architecture:**
|
|
||||||
- Microservices decomposition
|
|
||||||
- Event-driven architecture
|
|
||||||
- CQRS implementation where appropriate
|
|
||||||
- API design and optimization
|
|
||||||
|
|
||||||
**Scalability Enhancements:**
|
|
||||||
- Horizontal scaling strategies
|
|
||||||
- Database sharding and replication
|
|
||||||
- Caching layer implementation
|
|
||||||
- Load balancing optimization
|
|
||||||
|
|
||||||
## Deliverables
|
## Deliverables
|
||||||
- **Improvement Reports**: Detailed analysis of changes and their impact
|
|
||||||
- **Quality Metrics**: Before/after comparison of quality indicators
|
|
||||||
- **Performance Benchmarks**: Speed and efficiency improvements
|
|
||||||
- **Refactored Code**: Clean, optimized, and maintainable codebase
|
|
||||||
- **Documentation**: Updated docs reflecting improvements
|
|
||||||
|
|
||||||
## Output Locations
|
**Improved Code:** Refactored files | Preserved functionality | Enhanced quality | Better performance
|
||||||
- **Reports**: `.claudedocs/metrics/improvement-{type}-{timestamp}.md`
|
|
||||||
- **Benchmarks**: `.claudedocs/metrics/performance-{timestamp}.json`
|
|
||||||
- **Quality Metrics**: `.claudedocs/metrics/quality-{timestamp}.md`
|
|
||||||
|
|
||||||
## Research Requirements
|
**Improvement Report:** Before/after metrics | Changes summary | Performance gains | Quality improvements
|
||||||
External_Library_Research:
|
|
||||||
- Identify library/framework mentioned
|
|
||||||
- Context7 lookup for official documentation
|
|
||||||
- Verify API patterns and examples
|
|
||||||
- Check version compatibility
|
|
||||||
- Document findings in implementation
|
|
||||||
Pattern_Research:
|
|
||||||
- Search existing codebase for similar patterns
|
|
||||||
- Magic component search if UI-related
|
|
||||||
- WebSearch for official documentation
|
|
||||||
- Validate approach with Sequential thinking
|
|
||||||
- Document pattern choice rationale
|
|
||||||
API_Integration_Research:
|
|
||||||
- Official documentation lookup
|
|
||||||
- Authentication requirements
|
|
||||||
- Rate limiting and error handling
|
|
||||||
- SDK availability and examples
|
|
||||||
- Integration testing approach
|
|
||||||
|
|
||||||
## Report Notifications
|
**Documentation:** Refactoring decisions | Architecture changes | Performance optimizations | Future recommendations
|
||||||
📄 Analysis report saved to: {path}
|
|
||||||
📊 Metrics updated: {path}
|
|
||||||
📋 Summary saved to: {path}
|
|
||||||
💾 Checkpoint created: {path}
|
|
||||||
📚 Documentation created: {path}
|
|
||||||
📁 Created directory: {path}
|
|
||||||
✅ {operation} completed successfully
|
|
||||||
❌ {operation} failed: {reason}
|
|
||||||
⚠ {operation} completed w/ warnings
|
|
||||||
|
|
||||||
## Best Practices
|
@include shared/universal-constants.yml#Success_Messages
|
||||||
|
|
||||||
**Improvement Methodology:**
|
|
||||||
1. **Measure Before Changing**: Establish baseline metrics
|
|
||||||
2. **Focus on Bottlenecks**: Address highest impact issues first
|
|
||||||
3. **Incremental Changes**: Make one improvement at a time
|
|
||||||
4. **Verify Improvements**: Validate changes with metrics
|
|
||||||
5. **Document Changes**: Record what was changed and why
|
|
||||||
6. **Consider Trade-offs**: Balance competing concerns
|
|
||||||
|
|
||||||
**Common Pitfalls to Avoid:**
|
|
||||||
- Premature optimization without profiling
|
|
||||||
- Over-engineering simple solutions
|
|
||||||
- Breaking changes without proper testing
|
|
||||||
- Ignoring existing test suite
|
|
||||||
- Gold-plating beyond requirements
|
|
||||||
|
|
||||||
**Balance Considerations:**
|
|
||||||
- Performance vs code readability
|
|
||||||
- Flexibility vs simplicity
|
|
||||||
- Speed vs correctness
|
|
||||||
- Present needs vs future scalability
|
|
||||||
|
|
||||||
## Common Improvement Scenarios
|
|
||||||
|
|
||||||
### Code Quality Issues
|
|
||||||
```bash
|
|
||||||
/improve --quality --solid --metrics --dry-run
|
|
||||||
# → Identifies SOLID principle violations
|
|
||||||
# → Suggests refactoring for better modularity
|
|
||||||
# → Measures complexity metrics before/after changes
|
|
||||||
```
|
|
||||||
|
|
||||||
### Performance Bottlenecks
|
|
||||||
```bash
|
|
||||||
/improve --performance --iterate --threshold 90%
|
|
||||||
# → Profiles CPU and memory usage patterns
|
|
||||||
# → Implements algorithmic optimizations
|
|
||||||
# → Continues until 90% performance threshold met
|
|
||||||
```
|
|
||||||
|
|
||||||
### Technical Debt Reduction
|
|
||||||
```bash
|
|
||||||
/improve --quality --iterate --technical-debt
|
|
||||||
# → Identifies code duplication and anti-patterns
|
|
||||||
# → Suggests consolidation opportunities
|
|
||||||
# → Implements incremental refactoring strategy
|
|
||||||
```
|
|
||||||
|
|
||||||
### Error Handling Enhancement
|
|
||||||
```bash
|
|
||||||
/improve --resilience --error-handling --comprehensive
|
|
||||||
# → Reviews exception handling patterns
|
|
||||||
# → Implements proper logging and monitoring
|
|
||||||
# → Adds circuit breakers and retry mechanisms
|
|
||||||
```
|
|
||||||
|
|
||||||
## Troubleshooting
|
|
||||||
- **Complex Codebases**: Use `--iterate --interactive` for guided improvements
|
|
||||||
- **Performance Issues**: Combine `--performance --profile --seq` for deep analysis
|
|
||||||
- **Quality Problems**: Apply `--quality --solid --metrics` for comprehensive fixes
|
|
||||||
- **Architecture Concerns**: Use `--architecture --think-hard` for system-wide improvements
|
|
||||||
|
|
||||||
## Success Messages
|
|
||||||
✅ {operation} completed successfully
|
|
||||||
📝 Created: {file_path}
|
|
||||||
✏ Updated: {file_path}
|
|
||||||
✨ Task completed: {task_title}
|
|
||||||
@@ -37,17 +37,14 @@
|
|||||||
## Purpose
|
## Purpose
|
||||||
Comprehensive reference guide for all SuperClaude commands, workflows, and system capabilities.
|
Comprehensive reference guide for all SuperClaude commands, workflows, and system capabilities.
|
||||||
|
|
||||||
## Universal Flags
|
## Optimization Update (v4.0.0)
|
||||||
--plan: "Show execution plan before running"
|
🎯 **Major Streamlining Completed**: All 18 command files optimized using @include references
|
||||||
--uc: "UltraCompressed mode (~70% token reduction)"
|
- **Token Reduction**: ~70% reduction in command file size
|
||||||
--ultracompressed: "Alias for --uc"
|
- **Maintainability**: Single source of truth for all shared content
|
||||||
--think: "Multi-file analysis w/ context (4K tokens)"
|
- **Consistency**: Guaranteed uniformity across commands
|
||||||
--think-hard: "Deep architectural analysis (10K tokens)"
|
- **Reference System**: Commands now use shared patterns from `shared/*.yml` files
|
||||||
--ultrathink: "Critical system redesign (32K tokens)"
|
|
||||||
--c7: "Enable Context7→library documentation lookup"
|
@include shared/flag-inheritance.yml#Universal_Always
|
||||||
--seq: "Enable Sequential→complex analysis & thinking"
|
|
||||||
--magic: "Enable Magic→UI component generation"
|
|
||||||
--pup: "Enable Puppeteer→browser automation & testing"
|
|
||||||
--all-mcp: "Enable all MCP servers"
|
--all-mcp: "Enable all MCP servers"
|
||||||
--no-mcp: "Disable all MCP servers (native tools only)"
|
--no-mcp: "Disable all MCP servers (native tools only)"
|
||||||
--no-c7: "Disable Context7 specifically"
|
--no-c7: "Disable Context7 specifically"
|
||||||
|
|||||||
@@ -1,38 +1,7 @@
|
|||||||
# /load - Load and analyze project context
|
# /load - Load and analyze project context
|
||||||
|
|
||||||
## Legend
|
## Legend
|
||||||
| Symbol | Meaning | | Abbrev | Meaning |
|
@include shared/universal-constants.yml#Universal_Legend
|
||||||
|--------|---------|---|--------|---------|
|
|
||||||
| → | leads to | | cfg | configuration |
|
|
||||||
| & | and/with | | impl | implementation |
|
|
||||||
| w/ | with | | perf | performance |
|
|
||||||
| @ | at/located | | ops | operations |
|
|
||||||
| > | greater than | | val | validation |
|
|
||||||
| ∀ | for all/every | | req | requirements |
|
|
||||||
| ∃ | exists/there is | | deps | dependencies |
|
|
||||||
| ∴ | therefore | | env | environment |
|
|
||||||
| ∵ | because | | db | database |
|
|
||||||
| ≡ | equivalent | | api | interface |
|
|
||||||
| ≈ | approximately | | docs | documentation |
|
|
||||||
| 📁 | directory/path | | std | standard |
|
|
||||||
| 🔢 | number/count | | def | default |
|
|
||||||
| 📝 | text/string | | ctx | context |
|
|
||||||
| ⚙ | setting/config | | err | error |
|
|
||||||
| 🎛 | control/flags | | exec | execution |
|
|
||||||
| 🔧 | configuration | | qual | quality |
|
|
||||||
| 📋 | group/category | | rec | recovery |
|
|
||||||
| 🚨 | critical/urgent | | sev | severity |
|
|
||||||
| ⚠ | warning/caution | | resp | response |
|
|
||||||
| 🔄 | retry/recovery | | esc | escalation |
|
|
||||||
| ✅ | success/fixed | | tok | token |
|
|
||||||
| ❌ | failure/error | | opt | optimization |
|
|
||||||
| ℹ | information | | UX | user experience |
|
|
||||||
| ⚡ | fast/quick | | UI | user interface |
|
|
||||||
| 🐌 | slow/delayed | | C | critical |
|
|
||||||
| ✨ | complete/done | | H | high |
|
|
||||||
| 📖 | read operation | | M | medium |
|
|
||||||
| ✏ | edit operation | | L | low |
|
|
||||||
| 🗑 | delete operation | | |
|
|
||||||
|
|
||||||
## Purpose
|
## Purpose
|
||||||
Load and analyze project context in $ARGUMENTS to build comprehensive understanding of codebase structure, architecture, and patterns.
|
Load and analyze project context in $ARGUMENTS to build comprehensive understanding of codebase structure, architecture, and patterns.
|
||||||
@@ -40,217 +9,136 @@ Load and analyze project context in $ARGUMENTS to build comprehensive understand
|
|||||||
## Syntax
|
## Syntax
|
||||||
`/load [flags] [path]`
|
`/load [flags] [path]`
|
||||||
|
|
||||||
## Universal Flags
|
@include shared/flag-inheritance.yml#Universal_Always
|
||||||
--plan: "Show execution plan before running"
|
|
||||||
--uc: "UltraCompressed mode (~70% token reduction)"
|
|
||||||
--ultracompressed: "Alias for --uc"
|
|
||||||
--think: "Multi-file analysis w/ context (4K tokens)"
|
|
||||||
--think-hard: "Deep architectural analysis (10K tokens)"
|
|
||||||
--ultrathink: "Critical system redesign (32K tokens)"
|
|
||||||
--c7: "Enable Context7→library documentation lookup"
|
|
||||||
--seq: "Enable Sequential→complex analysis & thinking"
|
|
||||||
--magic: "Enable Magic→UI component generation"
|
|
||||||
--pup: "Enable Puppeteer→browser automation & testing"
|
|
||||||
--all-mcp: "Enable all MCP servers"
|
|
||||||
--no-mcp: "Disable all MCP servers (native tools only)"
|
|
||||||
--no-c7: "Disable Context7 specifically"
|
|
||||||
--no-seq: "Disable Sequential thinking specifically"
|
|
||||||
--no-magic: "Disable Magic UI builder specifically"
|
|
||||||
--no-pup: "Disable Puppeteer specifically"
|
|
||||||
|
|
||||||
## Command-Specific Flags
|
## Core Flags
|
||||||
|
|
||||||
**Analysis Depth:**
|
--scope flag:
|
||||||
- `--depth shallow`: Quick overview of project structure and purpose
|
- minimal: Core files only
|
||||||
- `--depth normal`: Standard analysis of main files and architecture (default)
|
- standard: Main source & config
|
||||||
- `--depth deep`: Comprehensive analysis of entire codebase
|
- comprehensive: All relevant files
|
||||||
|
- full: Complete project analysis
|
||||||
|
|
||||||
**Analysis Focus:**
|
--focus flag:
|
||||||
- `--architecture`: Focus on system design and component relationships
|
- architecture: System design
|
||||||
- `--dependencies`: Analyze dependency graph and package relationships
|
- api: API endpoints & contracts
|
||||||
- `--security`: Include security considerations and potential issues
|
- database: Schema & queries
|
||||||
- `--performance`: Identify performance patterns and potential bottlenecks
|
- frontend: UI components
|
||||||
- `--testing`: Analyze testing approach and coverage patterns
|
- testing: Test coverage
|
||||||
|
|
||||||
**Output Control:**
|
--format flag:
|
||||||
- `--summary`: Generate concise project overview
|
- summary: High-level overview
|
||||||
- `--detailed`: Include comprehensive analysis details
|
- detailed: Comprehensive analysis
|
||||||
- `--recommendations`: Provide actionable next steps and improvements
|
- visual: Include diagrams
|
||||||
|
- structured: YAML/JSON output
|
||||||
|
|
||||||
|
## Loading Strategy
|
||||||
|
|
||||||
|
Progressive Loading:
|
||||||
|
1. Core files (package.json, config)
|
||||||
|
2. Entry points (main, index)
|
||||||
|
3. Key modules & components
|
||||||
|
4. Tests & documentation
|
||||||
|
5. Supporting files
|
||||||
|
|
||||||
|
Smart Selection:
|
||||||
|
- Prioritize by importance
|
||||||
|
- Skip generated files
|
||||||
|
- Focus on active code
|
||||||
|
- Include critical configs
|
||||||
|
- Respect .gitignore
|
||||||
|
|
||||||
|
## Analysis Components
|
||||||
|
|
||||||
|
Structure Analysis:
|
||||||
|
- Directory organization
|
||||||
|
- Module dependencies
|
||||||
|
- Component hierarchy
|
||||||
|
- API surface area
|
||||||
|
- Database schema
|
||||||
|
|
||||||
|
Pattern Detection:
|
||||||
|
- Design patterns used
|
||||||
|
- Coding conventions
|
||||||
|
- Architecture style
|
||||||
|
- Technology stack
|
||||||
|
- Best practices
|
||||||
|
|
||||||
|
Quality Metrics:
|
||||||
|
- Code complexity
|
||||||
|
- Test coverage
|
||||||
|
- Documentation level
|
||||||
|
- Technical debt
|
||||||
|
- Security concerns
|
||||||
|
|
||||||
|
## Output Format
|
||||||
|
|
||||||
|
Standard Report:
|
||||||
|
```yaml
|
||||||
|
Project: [Name]
|
||||||
|
Type: [Web App/API/Library]
|
||||||
|
Stack:
|
||||||
|
Frontend: [Technologies]
|
||||||
|
Backend: [Technologies]
|
||||||
|
Database: [Type]
|
||||||
|
Architecture:
|
||||||
|
Style: [Monolith/Microservices]
|
||||||
|
Patterns: [List]
|
||||||
|
Key_Components:
|
||||||
|
- [Component]: [Purpose]
|
||||||
|
Quality:
|
||||||
|
Test_Coverage: X%
|
||||||
|
Documentation: [Level]
|
||||||
|
Complexity: [Score]
|
||||||
|
```
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
Efficiency:
|
||||||
|
- Load incrementally
|
||||||
|
- Cache analysis results
|
||||||
|
- Focus on changes
|
||||||
|
- Skip redundant files
|
||||||
|
- Optimize memory usage
|
||||||
|
|
||||||
|
Accuracy:
|
||||||
|
- Verify assumptions
|
||||||
|
- Cross-reference files
|
||||||
|
- Check documentation
|
||||||
|
- Validate patterns
|
||||||
|
- Update regularly
|
||||||
|
|
||||||
## Examples
|
## Examples
|
||||||
- `/load --depth shallow` → Quick project overview
|
|
||||||
- `/load --depth deep --architecture` → Comprehensive architectural analysis
|
|
||||||
- `/load --dependencies --security` → Focus on deps and security
|
|
||||||
- `/load --performance --testing --detailed` → Performance and testing analysis
|
|
||||||
- `/load --summary --recommendations` → Overview with actionable insights
|
|
||||||
|
|
||||||
## Loading Process
|
```bash
|
||||||
|
# Quick project overview
|
||||||
|
/load --scope minimal
|
||||||
|
|
||||||
**1. Project Structure Scan:**
|
# Full architecture analysis
|
||||||
- Directory layout and organization
|
/load --scope comprehensive --focus architecture
|
||||||
- File types and distribution
|
|
||||||
- Module boundaries and hierarchies
|
|
||||||
- Entry points and main components
|
|
||||||
|
|
||||||
**2. Configuration Analysis:**
|
# API documentation generation
|
||||||
- Package manifests (package.json, requirements.txt, go.mod)
|
/load --focus api --format detailed
|
||||||
- Build configurations (webpack, vite, rollup)
|
|
||||||
- Environment and deployment configs
|
|
||||||
- CI/CD pipeline definitions
|
|
||||||
|
|
||||||
**3. Code Architecture Review:**
|
# Complete project understanding
|
||||||
- Design patterns and architectural style
|
/load --scope full --think-hard
|
||||||
- Component relationships and dependencies
|
```
|
||||||
- Data flow and state management
|
|
||||||
- API structure and endpoints
|
|
||||||
|
|
||||||
**4. Development Environment:**
|
## Integration
|
||||||
- Git repository status and history
|
|
||||||
- Development workflow patterns
|
|
||||||
- Testing framework and approach
|
|
||||||
- Documentation quality and coverage
|
|
||||||
|
|
||||||
**5. Technology Stack Identification:**
|
@include shared/loading-config.yml#Loading_Strategies
|
||||||
- Frontend and backend technologies
|
|
||||||
- Database and data storage solutions
|
|
||||||
- Third-party integrations and services
|
|
||||||
- Development and deployment tools
|
|
||||||
|
|
||||||
## Analysis Depth Levels
|
Works with:
|
||||||
|
- /analyze for deep inspection
|
||||||
**Shallow Depth:**
|
- /document for documentation
|
||||||
- Project purpose and business goals
|
- /improve for enhancements
|
||||||
- Primary technologies and frameworks
|
- /estimate for planning
|
||||||
- High-level architecture overview
|
|
||||||
- Key dependencies and integrations
|
|
||||||
- Quick start and setup information
|
|
||||||
- Development team structure clues
|
|
||||||
|
|
||||||
**Normal Depth:**
|
|
||||||
- Detailed file and directory structure
|
|
||||||
- Main components and their responsibilities
|
|
||||||
- API endpoints, routes, and data models
|
|
||||||
- Database schema and relationships
|
|
||||||
- Testing strategy and coverage areas
|
|
||||||
- Development workflow and best practices
|
|
||||||
|
|
||||||
**Deep Depth:**
|
|
||||||
- Complete codebase analysis and mapping
|
|
||||||
- Detailed component interaction diagrams
|
|
||||||
- Comprehensive dependency relationships
|
|
||||||
- Performance characteristics and bottlenecks
|
|
||||||
- Security considerations and vulnerabilities
|
|
||||||
- Technical debt assessment
|
|
||||||
- Optimization opportunities and recommendations
|
|
||||||
|
|
||||||
## Essential Files Analysis
|
|
||||||
|
|
||||||
**Documentation:**
|
|
||||||
- README.md (project overview and setup)
|
|
||||||
- CONTRIBUTING.md (development guidelines)
|
|
||||||
- API documentation and specs
|
|
||||||
- Architecture decision records (ADRs)
|
|
||||||
|
|
||||||
**Configuration:**
|
|
||||||
- Package managers (package.json, yarn.lock, requirements.txt)
|
|
||||||
- Build tools (webpack.config.js, vite.config.ts)
|
|
||||||
- Environment configs (.env files, docker-compose.yml)
|
|
||||||
- CI/CD pipelines (.github/workflows, .gitlab-ci.yml)
|
|
||||||
|
|
||||||
**Source Code:**
|
|
||||||
- Entry points (main.js, app.py, index.html)
|
|
||||||
- Core modules and components
|
|
||||||
- Shared utilities and libraries
|
|
||||||
- Test files and test configurations
|
|
||||||
|
|
||||||
**Version Control:**
|
|
||||||
- Git history and commit patterns
|
|
||||||
- Branch strategy and naming conventions
|
|
||||||
- Recent changes and active development areas
|
|
||||||
- Contributor patterns and team structure
|
|
||||||
|
|
||||||
## Mental Model Construction
|
|
||||||
|
|
||||||
**System Understanding:**
|
|
||||||
- Component interaction patterns
|
|
||||||
- Data flow through the application
|
|
||||||
- External service integrations
|
|
||||||
- Deployment and infrastructure architecture
|
|
||||||
- User journey and experience flows
|
|
||||||
|
|
||||||
**Development Insights:**
|
|
||||||
- Code quality and consistency patterns
|
|
||||||
- Testing maturity and coverage
|
|
||||||
- Documentation completeness
|
|
||||||
- Development velocity indicators
|
|
||||||
- Technical debt and maintenance needs
|
|
||||||
|
|
||||||
## Deliverables
|
## Deliverables
|
||||||
- **Project Overview**: Comprehensive understanding summary
|
|
||||||
- **Architecture Map**: System design and component relationships
|
|
||||||
- **Technology Inventory**: Complete stack and dependency analysis
|
|
||||||
- **Development Guide**: Quick reference for project navigation
|
|
||||||
- **Recommendations**: Next steps and improvement opportunities
|
|
||||||
- **Risk Assessment**: Potential issues and technical debt areas
|
|
||||||
|
|
||||||
## Output Locations
|
- Project structure map
|
||||||
- **Analysis Reports**: `.claudedocs/summaries/project-analysis-{timestamp}.md`
|
- Architecture diagram
|
||||||
- **Architecture Docs**: `.claudedocs/summaries/architecture-overview-{timestamp}.md`
|
- Component inventory
|
||||||
- **Quick Reference**: `.claudedocs/summaries/project-guide-{timestamp}.md`
|
- Dependency graph
|
||||||
|
- Quality metrics report
|
||||||
## Research Requirements
|
- Pattern analysis
|
||||||
External_Library_Research:
|
|
||||||
- Identify library/framework mentioned
|
|
||||||
- Context7 lookup for official documentation
|
|
||||||
- Verify API patterns and examples
|
|
||||||
- Check version compatibility
|
|
||||||
- Document findings in implementation
|
|
||||||
Pattern_Research:
|
|
||||||
- Search existing codebase for similar patterns
|
|
||||||
- Magic component search if UI-related
|
|
||||||
- WebSearch for official documentation
|
|
||||||
- Validate approach with Sequential thinking
|
|
||||||
- Document pattern choice rationale
|
|
||||||
API_Integration_Research:
|
|
||||||
- Official documentation lookup
|
|
||||||
- Authentication requirements
|
|
||||||
- Rate limiting and error handling
|
|
||||||
- SDK availability and examples
|
|
||||||
- Integration testing approach
|
|
||||||
|
|
||||||
## Report Notifications
|
|
||||||
📄 Analysis report saved to: {path}
|
|
||||||
📊 Metrics updated: {path}
|
|
||||||
📋 Summary saved to: {path}
|
|
||||||
💾 Checkpoint created: {path}
|
|
||||||
📚 Documentation created: {path}
|
|
||||||
📁 Created directory: {path}
|
|
||||||
✅ {operation} completed successfully
|
|
||||||
❌ {operation} failed: {reason}
|
|
||||||
⚠ {operation} completed w/ warnings
|
|
||||||
|
|
||||||
## Integration Patterns
|
|
||||||
|
|
||||||
**Workflow Integration:**
|
|
||||||
- Load project context before major development work
|
|
||||||
- Refresh understanding after significant changes
|
|
||||||
- Share context with team members and new contributors
|
|
||||||
- Use as foundation for architecture decisions
|
|
||||||
|
|
||||||
**Command Chaining:**
|
|
||||||
- `load` → `analyze --architecture` for design review
|
|
||||||
- `load` → `scan --security` for security assessment
|
|
||||||
- `load` → `improve --quality` for refactoring planning
|
|
||||||
- `load` → `document --architecture` for documentation
|
|
||||||
|
|
||||||
## Troubleshooting
|
|
||||||
- **Large Codebases**: Use `--depth shallow` for initial overview
|
|
||||||
- **Complex Architecture**: Combine `--architecture --detailed` for comprehensive analysis
|
|
||||||
- **Performance Issues**: Include `--performance` flag for optimization insights
|
|
||||||
- **Security Concerns**: Add `--security` flag for vulnerability assessment
|
|
||||||
|
|
||||||
## Success Messages
|
|
||||||
✅ {operation} completed successfully
|
|
||||||
📝 Created: {file_path}
|
|
||||||
✏ Updated: {file_path}
|
|
||||||
✨ Task completed: {task_title}
|
|
||||||
@@ -1,38 +1,7 @@
|
|||||||
# /migrate - Execute database and code migrations
|
# /migrate - Execute database and code migrations
|
||||||
|
|
||||||
## Legend
|
## Legend
|
||||||
| Symbol | Meaning | | Abbrev | Meaning |
|
@include shared/universal-constants.yml#Universal_Legend
|
||||||
|--------|---------|---|--------|---------|
|
|
||||||
| → | leads to | | cfg | configuration |
|
|
||||||
| & | and/with | | impl | implementation |
|
|
||||||
| w/ | with | | perf | performance |
|
|
||||||
| @ | at/located | | ops | operations |
|
|
||||||
| > | greater than | | val | validation |
|
|
||||||
| ∀ | for all/every | | req | requirements |
|
|
||||||
| ∃ | exists/there is | | deps | dependencies |
|
|
||||||
| ∴ | therefore | | env | environment |
|
|
||||||
| ∵ | because | | db | database |
|
|
||||||
| ≡ | equivalent | | api | interface |
|
|
||||||
| ≈ | approximately | | docs | documentation |
|
|
||||||
| 📁 | directory/path | | std | standard |
|
|
||||||
| 🔢 | number/count | | def | default |
|
|
||||||
| 📝 | text/string | | ctx | context |
|
|
||||||
| ⚙ | setting/config | | err | error |
|
|
||||||
| 🎛 | control/flags | | exec | execution |
|
|
||||||
| 🔧 | configuration | | qual | quality |
|
|
||||||
| 📋 | group/category | | rec | recovery |
|
|
||||||
| 🚨 | critical/urgent | | sev | severity |
|
|
||||||
| ⚠ | warning/caution | | resp | response |
|
|
||||||
| 🔄 | retry/recovery | | esc | escalation |
|
|
||||||
| ✅ | success/fixed | | tok | token |
|
|
||||||
| ❌ | failure/error | | opt | optimization |
|
|
||||||
| ℹ | information | | UX | user experience |
|
|
||||||
| ⚡ | fast/quick | | UI | user interface |
|
|
||||||
| 🐌 | slow/delayed | | C | critical |
|
|
||||||
| ✨ | complete/done | | H | high |
|
|
||||||
| 📖 | read operation | | M | medium |
|
|
||||||
| ✏ | edit operation | | L | low |
|
|
||||||
| 🗑 | delete operation | | |
|
|
||||||
|
|
||||||
## Purpose
|
## Purpose
|
||||||
Execute comprehensive database or code migrations based on specifications in $ARGUMENTS with safety checks and rollback capabilities.
|
Execute comprehensive database or code migrations based on specifications in $ARGUMENTS with safety checks and rollback capabilities.
|
||||||
@@ -40,264 +9,138 @@ Execute comprehensive database or code migrations based on specifications in $AR
|
|||||||
## Syntax
|
## Syntax
|
||||||
`/migrate [flags] [migration-spec]`
|
`/migrate [flags] [migration-spec]`
|
||||||
|
|
||||||
## Universal Flags
|
@include shared/flag-inheritance.yml#Universal_Always
|
||||||
--plan: "Show execution plan before running"
|
|
||||||
--uc: "UltraCompressed mode (~70% token reduction)"
|
|
||||||
--ultracompressed: "Alias for --uc"
|
|
||||||
--think: "Multi-file analysis w/ context (4K tokens)"
|
|
||||||
--think-hard: "Deep architectural analysis (10K tokens)"
|
|
||||||
--ultrathink: "Critical system redesign (32K tokens)"
|
|
||||||
--c7: "Enable Context7→library documentation lookup"
|
|
||||||
--seq: "Enable Sequential→complex analysis & thinking"
|
|
||||||
--magic: "Enable Magic→UI component generation"
|
|
||||||
--pup: "Enable Puppeteer→browser automation & testing"
|
|
||||||
--all-mcp: "Enable all MCP servers"
|
|
||||||
--no-mcp: "Disable all MCP servers (native tools only)"
|
|
||||||
--no-c7: "Disable Context7 specifically"
|
|
||||||
--no-seq: "Disable Sequential thinking specifically"
|
|
||||||
--no-magic: "Disable Magic UI builder specifically"
|
|
||||||
--no-pup: "Disable Puppeteer specifically"
|
|
||||||
|
|
||||||
## Command-Specific Flags
|
## Core Flags
|
||||||
|
|
||||||
**Migration Types:**
|
--type flag:
|
||||||
- `--schema`: Database schema migrations (tables, indexes, constraints)
|
- database: SQL schema migrations
|
||||||
- `--data`: Data transformation and migration operations
|
- code: Codebase refactoring
|
||||||
- `--code`: Code refactoring and modernization migrations
|
- api: API version migration
|
||||||
- `--framework`: Framework or library version migrations
|
- data: Data transformation
|
||||||
- `--config`: Configuration and environment migrations
|
- full: Complete system migration
|
||||||
|
|
||||||
**Execution Control:**
|
--direction flag:
|
||||||
- `--dry-run`: Preview changes without execution
|
- up: Apply migrations forward
|
||||||
- `--rollback`: Revert to pre-migration state
|
- down: Rollback migrations
|
||||||
- `--checkpoint`: Create checkpoint before migration
|
- status: Check migration state
|
||||||
- `--force`: Override safety checks (use with caution)
|
- validate: Test without applying
|
||||||
|
|
||||||
**Safety & Validation:**
|
--target flag:
|
||||||
- `--backup`: Create full backup before migration
|
- latest: All pending migrations
|
||||||
- `--validate`: Validate migration integrity and consistency
|
- version: Specific version
|
||||||
- `--test-mode`: Run in isolated test environment
|
- step: Number of migrations
|
||||||
- `--zero-downtime`: Implement zero-downtime migration strategy
|
- timestamp: Up to date/time
|
||||||
|
|
||||||
**Monitoring:**
|
|
||||||
- `--progress`: Show detailed progress during migration
|
|
||||||
- `--log-level [level]`: Set logging verbosity (info|debug|trace)
|
|
||||||
- `--timeout [seconds]`: Set maximum migration duration
|
|
||||||
|
|
||||||
## Examples
|
|
||||||
- `/migrate --schema --dry-run --think` → Schema migration preview with analysis
|
|
||||||
- `/migrate --data --backup --validate --think-hard` → Data migration with safety checks
|
|
||||||
- `/migrate --framework --zero-downtime --ultrathink` → Framework upgrade with zero downtime
|
|
||||||
- `/migrate --rollback --checkpoint restore-20240115` → Rollback to specific checkpoint
|
|
||||||
- `/migrate --code --test-mode --progress` → Code migration in test environment
|
|
||||||
|
|
||||||
## Migration Types
|
## Migration Types
|
||||||
|
|
||||||
**Schema Migrations:**
|
Database Migrations:
|
||||||
- Create, alter, or drop database tables
|
- Schema changes (add/drop tables)
|
||||||
- Add or modify indexes for performance
|
- Column modifications
|
||||||
- Update constraints and relationships
|
- Index optimization
|
||||||
- Manage database versioning and compatibility
|
- Constraint updates
|
||||||
- Handle foreign key dependencies
|
- Data transformations
|
||||||
|
|
||||||
**Data Migrations:**
|
Code Migrations:
|
||||||
- Transform existing data to new formats
|
- API version updates
|
||||||
- Backfill missing or derived data fields
|
- Framework upgrades
|
||||||
- Clean up obsolete or orphaned records
|
- Dependency updates
|
||||||
- Ensure referential integrity throughout process
|
- Structure refactoring
|
||||||
- Handle large dataset migrations efficiently
|
- Pattern modernization
|
||||||
|
|
||||||
**Code Migrations:**
|
Data Migrations:
|
||||||
- Refactor to new architectural patterns
|
- Format conversions
|
||||||
- Update to new framework versions
|
- Bulk transformations
|
||||||
- Migrate between different technologies
|
- ETL operations
|
||||||
- Modernize legacy code and patterns
|
- Cleanup operations
|
||||||
- Update API contracts and interfaces
|
- Normalization
|
||||||
|
|
||||||
**Framework Migrations:**
|
## Safety Features
|
||||||
- Upgrade major framework versions
|
|
||||||
- Migrate between competing frameworks
|
|
||||||
- Update dependency chains
|
|
||||||
- Handle breaking changes systematically
|
|
||||||
- Maintain backward compatibility where possible
|
|
||||||
|
|
||||||
## Safe Migration Workflow
|
Pre-Migration:
|
||||||
|
- Backup current state
|
||||||
|
- Validate migration files
|
||||||
|
- Check dependencies
|
||||||
|
- Test in transaction
|
||||||
|
- Estimate impact
|
||||||
|
|
||||||
**1. Planning Phase:**
|
During Migration:
|
||||||
- Analyze migration requirements and scope
|
- Transaction wrapping
|
||||||
- Design migration strategy and approach
|
- Progress tracking
|
||||||
- Create comprehensive rollback plan
|
- Error handling
|
||||||
- Identify dependencies and prerequisites
|
- Partial rollback
|
||||||
- Estimate duration and resource requirements
|
- Health checks
|
||||||
|
|
||||||
**2. Preparation Phase:**
|
Post-Migration:
|
||||||
- Create full backup of affected systems
|
- Verify integrity
|
||||||
- Set up isolated test environment
|
- Update documentation
|
||||||
- Prepare migration scripts and procedures
|
- Clear caches
|
||||||
- Validate rollback procedures
|
- Run tests
|
||||||
- Notify stakeholders and schedule downtime
|
- Monitor performance
|
||||||
|
|
||||||
**3. Testing Phase:**
|
## Migration Workflow
|
||||||
- Run migration in test environment
|
|
||||||
- Validate data integrity and functionality
|
|
||||||
- Test rollback procedures
|
|
||||||
- Performance test with realistic data
|
|
||||||
- Document any issues and resolutions
|
|
||||||
|
|
||||||
**4. Execution Phase:**
|
1. Analysis Phase:
|
||||||
- Apply migration with transaction support
|
- Scan current state
|
||||||
- Monitor system performance and health
|
- Identify changes needed
|
||||||
- Track progress and log all operations
|
- Generate migration plan
|
||||||
- Handle errors gracefully with fallbacks
|
- Estimate risks
|
||||||
- Maintain communication with stakeholders
|
|
||||||
|
|
||||||
**5. Verification Phase:**
|
2. Preparation Phase:
|
||||||
- Validate migration success and completeness
|
- Create backups
|
||||||
- Verify data integrity with checksums
|
- Prepare rollback plan
|
||||||
- Run comprehensive test suite
|
- Set up monitoring
|
||||||
- Monitor system stability post-migration
|
- Notify stakeholders
|
||||||
- Document lessons learned and improvements
|
|
||||||
|
|
||||||
## Dry Run Operations (--dry-run)
|
3. Execution Phase:
|
||||||
|
- Run migrations
|
||||||
|
- Track progress
|
||||||
|
- Handle errors
|
||||||
|
- Apply fixes
|
||||||
|
|
||||||
**Preview Capabilities:**
|
4. Validation Phase:
|
||||||
- Show all changes without executing them
|
- Verify success
|
||||||
- Display affected records and files count
|
- Run test suite
|
||||||
- Estimate migration duration and resource usage
|
- Check performance
|
||||||
- Identify potential issues and conflicts
|
- Update docs
|
||||||
- Generate detailed execution plan
|
|
||||||
|
|
||||||
**Risk Assessment:**
|
|
||||||
- Analyze impact on system performance
|
|
||||||
- Identify data integrity risks
|
|
||||||
- Assess rollback complexity
|
|
||||||
- Evaluate downtime requirements
|
|
||||||
- Calculate resource utilization
|
|
||||||
|
|
||||||
## Rollback Operations (--rollback)
|
|
||||||
|
|
||||||
**Rollback Strategies:**
|
|
||||||
- Transaction-based rollback for database changes
|
|
||||||
- Backup restoration for complex changes
|
|
||||||
- Code version control reversion
|
|
||||||
- Configuration rollback procedures
|
|
||||||
- Progressive rollback for staged migrations
|
|
||||||
|
|
||||||
**Rollback Verification:**
|
|
||||||
- Verify system returns to pre-migration state
|
|
||||||
- Validate data integrity after rollback
|
|
||||||
- Test system functionality completely
|
|
||||||
- Monitor performance and stability
|
|
||||||
- Document rollback effectiveness
|
|
||||||
|
|
||||||
## Zero-Downtime Migrations (--zero-downtime)
|
|
||||||
|
|
||||||
**Strategies:**
|
|
||||||
- Blue-green deployment patterns
|
|
||||||
- Rolling updates with health checks
|
|
||||||
- Shadow migration and cutover
|
|
||||||
- Feature flags for gradual rollout
|
|
||||||
- Database read replica promotion
|
|
||||||
|
|
||||||
**Implementation:**
|
|
||||||
- Maintain dual-write compatibility
|
|
||||||
- Implement backward-compatible schemas
|
|
||||||
- Use load balancers for traffic switching
|
|
||||||
- Monitor key metrics during transition
|
|
||||||
- Prepare instant rollback mechanisms
|
|
||||||
|
|
||||||
## Safety Measures
|
|
||||||
|
|
||||||
**Data Protection:**
|
|
||||||
- Automatic backup creation before migration
|
|
||||||
- Transaction atomicity for database operations
|
|
||||||
- Checksum validation for data integrity
|
|
||||||
- Idempotent migration scripts
|
|
||||||
- Recovery point objectives (RPO) compliance
|
|
||||||
|
|
||||||
**System Protection:**
|
|
||||||
- Resource usage monitoring and limits
|
|
||||||
- Timeout protection for long operations
|
|
||||||
- Health checks and circuit breakers
|
|
||||||
- Progressive execution with validation
|
|
||||||
- Automated rollback triggers
|
|
||||||
|
|
||||||
## Deliverables
|
|
||||||
- **Migration Scripts**: Complete, tested migration procedures
|
|
||||||
- **Execution Report**: Detailed migration statistics and outcomes
|
|
||||||
- **Backup Confirmation**: Verified backup creation and integrity
|
|
||||||
- **Data Integrity Report**: Validation of data consistency post-migration
|
|
||||||
- **Rollback Procedures**: Documented and tested rollback plans
|
|
||||||
- **Performance Metrics**: Before/after performance comparisons
|
|
||||||
|
|
||||||
## Output Locations
|
|
||||||
- **Migration Logs**: `.claudedocs/reports/migration-{timestamp}.md`
|
|
||||||
- **Data Validation**: `.claudedocs/metrics/data-validation-{timestamp}.md`
|
|
||||||
- **Rollback Plans**: `.claudedocs/summaries/rollback-plan-{timestamp}.md`
|
|
||||||
- **Performance Reports**: `.claudedocs/metrics/migration-performance-{timestamp}.md`
|
|
||||||
|
|
||||||
## Research Requirements
|
|
||||||
External_Library_Research:
|
|
||||||
- Identify library/framework mentioned
|
|
||||||
- Context7 lookup for official documentation
|
|
||||||
- Verify API patterns and examples
|
|
||||||
- Check version compatibility
|
|
||||||
- Document findings in implementation
|
|
||||||
Pattern_Research:
|
|
||||||
- Search existing codebase for similar patterns
|
|
||||||
- Magic component search if UI-related
|
|
||||||
- WebSearch for official documentation
|
|
||||||
- Validate approach with Sequential thinking
|
|
||||||
- Document pattern choice rationale
|
|
||||||
API_Integration_Research:
|
|
||||||
- Official documentation lookup
|
|
||||||
- Authentication requirements
|
|
||||||
- Rate limiting and error handling
|
|
||||||
- SDK availability and examples
|
|
||||||
- Integration testing approach
|
|
||||||
|
|
||||||
## Report Notifications
|
|
||||||
📄 Analysis report saved to: {path}
|
|
||||||
📊 Metrics updated: {path}
|
|
||||||
📋 Summary saved to: {path}
|
|
||||||
💾 Checkpoint created: {path}
|
|
||||||
📚 Documentation created: {path}
|
|
||||||
📁 Created directory: {path}
|
|
||||||
✅ {operation} completed successfully
|
|
||||||
❌ {operation} failed: {reason}
|
|
||||||
⚠ {operation} completed w/ warnings
|
|
||||||
|
|
||||||
## Best Practices
|
## Best Practices
|
||||||
|
|
||||||
**Planning:**
|
Safety:
|
||||||
- Always test migrations in staging environment
|
- Always backup first
|
||||||
- Create detailed rollback plans before execution
|
- Test in staging
|
||||||
- Communicate with stakeholders about timing
|
- Use transactions
|
||||||
- Plan for peak and off-peak execution windows
|
- Plan rollbacks
|
||||||
- Document all migration decisions and rationale
|
- Monitor closely
|
||||||
|
|
||||||
**Execution:**
|
Performance:
|
||||||
- Use transactions for atomicity where possible
|
- Batch operations
|
||||||
- Monitor system health throughout migration
|
- Off-peak execution
|
||||||
- Keep detailed logs of all operations
|
- Index management
|
||||||
- Have rollback procedures ready and tested
|
- Query optimization
|
||||||
- Validate data integrity at each step
|
- Resource limits
|
||||||
|
|
||||||
**Post-Migration:**
|
## Examples
|
||||||
- Verify system functionality completely
|
|
||||||
- Monitor performance for regression
|
|
||||||
- Clean up temporary migration artifacts
|
|
||||||
- Update documentation and procedures
|
|
||||||
- Conduct post-mortem for improvement
|
|
||||||
|
|
||||||
## Troubleshooting
|
```bash
|
||||||
- **Large Datasets**: Use `--progress --timeout` for monitoring
|
# Database migration to latest
|
||||||
- **Complex Dependencies**: Apply `--think-hard` for comprehensive planning
|
/migrate --type database --direction up
|
||||||
- **Production Systems**: Combine `--zero-downtime --backup --validate`
|
|
||||||
- **Failed Migrations**: Use `--rollback` with specific checkpoint
|
|
||||||
|
|
||||||
## Success Messages
|
# Rollback last 2 migrations
|
||||||
✅ {operation} completed successfully
|
/migrate --type database --direction down --step 2
|
||||||
📝 Created: {file_path}
|
|
||||||
✏ Updated: {file_path}
|
# Code migration with validation
|
||||||
✨ Task completed: {task_title}
|
/migrate --type code --validate --think
|
||||||
|
|
||||||
|
# Full system migration plan
|
||||||
|
/migrate --type full --plan --ultrathink
|
||||||
|
```
|
||||||
|
|
||||||
|
## Deliverables
|
||||||
|
|
||||||
|
- Migration scripts
|
||||||
|
- Rollback procedures
|
||||||
|
- Execution logs
|
||||||
|
- Validation reports
|
||||||
|
- Updated documentation
|
||||||
|
- Performance metrics
|
||||||
@@ -1,351 +1,57 @@
|
|||||||
# /scan - Perform security and validation scans
|
# /scan - Security and quality scanning
|
||||||
|
|
||||||
## Legend
|
@include shared/universal-constants.yml#Universal_Legend
|
||||||
| Symbol | Meaning | | Abbrev | Meaning |
|
|
||||||
|--------|---------|---|--------|---------|
|
|
||||||
| → | leads to | | cfg | configuration |
|
|
||||||
| & | and/with | | impl | implementation |
|
|
||||||
| w/ | with | | perf | performance |
|
|
||||||
| @ | at/located | | ops | operations |
|
|
||||||
| > | greater than | | val | validation |
|
|
||||||
| ∀ | for all/every | | req | requirements |
|
|
||||||
| ∃ | exists/there is | | deps | dependencies |
|
|
||||||
| ∴ | therefore | | env | environment |
|
|
||||||
| ∵ | because | | db | database |
|
|
||||||
| ≡ | equivalent | | api | interface |
|
|
||||||
| ≈ | approximately | | docs | documentation |
|
|
||||||
| 📁 | directory/path | | std | standard |
|
|
||||||
| 🔢 | number/count | | def | default |
|
|
||||||
| 📝 | text/string | | ctx | context |
|
|
||||||
| ⚙ | setting/config | | err | error |
|
|
||||||
| 🎛 | control/flags | | exec | execution |
|
|
||||||
| 🔧 | configuration | | qual | quality |
|
|
||||||
| 📋 | group/category | | rec | recovery |
|
|
||||||
| 🚨 | critical/urgent | | sev | severity |
|
|
||||||
| ⚠ | warning/caution | | resp | response |
|
|
||||||
| 🔄 | retry/recovery | | esc | escalation |
|
|
||||||
| ✅ | success/fixed | | tok | token |
|
|
||||||
| ❌ | failure/error | | opt | optimization |
|
|
||||||
| ℹ | information | | UX | user experience |
|
|
||||||
| ⚡ | fast/quick | | UI | user interface |
|
|
||||||
| 🐌 | slow/delayed | | C | critical |
|
|
||||||
| ✨ | complete/done | | H | high |
|
|
||||||
| 📖 | read operation | | M | medium |
|
|
||||||
| ✏ | edit operation | | L | low |
|
|
||||||
| 🗑 | delete operation | | |
|
|
||||||
|
|
||||||
## Purpose
|
## Purpose
|
||||||
Perform comprehensive security and validation scans on code, operations, or systems specified in $ARGUMENTS to identify vulnerabilities and safety issues.
|
Perform comprehensive security, quality, and dependency scanning on code specified in $ARGUMENTS.
|
||||||
|
|
||||||
## Syntax
|
## Syntax
|
||||||
`/scan [flags] [target]`
|
`/scan [flags] [target]`
|
||||||
|
|
||||||
## Universal Flags
|
@include shared/flag-inheritance.yml#Universal_Always
|
||||||
--plan: "Show execution plan before running"
|
|
||||||
--uc: "UltraCompressed mode (~70% token reduction)"
|
Examples:
|
||||||
--ultracompressed: "Alias for --uc"
|
- `/scan --security` - Security vulnerability scan
|
||||||
--think: "Multi-file analysis w/ context (4K tokens)"
|
- `/scan --deps` - Dependency audit
|
||||||
--think-hard: "Deep architectural analysis (10K tokens)"
|
- `/scan --validate` - Full validation scan
|
||||||
--ultrathink: "Critical system redesign (32K tokens)"
|
- `/scan --quick` - Quick scan for critical issues
|
||||||
--c7: "Enable Context7→library documentation lookup"
|
|
||||||
--seq: "Enable Sequential→complex analysis & thinking"
|
|
||||||
--magic: "Enable Magic→UI component generation"
|
|
||||||
--pup: "Enable Puppeteer→browser automation & testing"
|
|
||||||
--all-mcp: "Enable all MCP servers"
|
|
||||||
--no-mcp: "Disable all MCP servers (native tools only)"
|
|
||||||
--no-c7: "Disable Context7 specifically"
|
|
||||||
--no-seq: "Disable Sequential thinking specifically"
|
|
||||||
--no-magic: "Disable Magic UI builder specifically"
|
|
||||||
--no-pup: "Disable Puppeteer specifically"
|
|
||||||
|
|
||||||
## Command-Specific Flags
|
## Command-Specific Flags
|
||||||
|
--security: "Deep security vulnerability scanning (OWASP, CVEs, secrets)"
|
||||||
|
--deps: "Dependency vulnerability audit w/ fix recommendations"
|
||||||
|
--validate: "Comprehensive validation (syntax, types, logic, security)"
|
||||||
|
--quick: "Fast scan focusing on critical issues only"
|
||||||
|
--fix: "Auto-fix safe issues"
|
||||||
|
--strict: "Zero-tolerance mode (fail on any issue)"
|
||||||
|
--report: "Generate detailed report"
|
||||||
|
--ci: "CI-friendly output format"
|
||||||
|
|
||||||
**Scan Types:**
|
## Scan Types
|
||||||
- `--validate`: Pre-execution safety validation and risk assessment
|
|
||||||
- `--security`: Comprehensive security analysis and vulnerability scanning
|
|
||||||
- `--owasp`: Focus on OWASP Top 10 security risks
|
|
||||||
- `--deps`: Dependency vulnerability and license scanning
|
|
||||||
- `--config`: Configuration security and compliance checking
|
|
||||||
|
|
||||||
**Scan Depth:**
|
**Security Scan:** OWASP Top 10 | Injection vulnerabilities | Auth flaws | Sensitive data exposure | Hardcoded secrets | CVE database check
|
||||||
- `--quick`: Fast validation for common issues with rapid feedback
|
|
||||||
- `--comprehensive`: Deep analysis covering all security aspects
|
|
||||||
- `--strict`: Zero-tolerance mode flagging all potential issues
|
|
||||||
|
|
||||||
**Specialized Scans:**
|
**Dependency Scan:** Known vulnerabilities | Outdated packages | License compliance | Supply chain risks | Transitive dependencies
|
||||||
- `--infrastructure`: Infrastructure and deployment security
|
|
||||||
- `--code`: Source code security analysis
|
|
||||||
- `--data`: Data protection and privacy compliance
|
|
||||||
- `--network`: Network security and exposure analysis
|
|
||||||
|
|
||||||
**Output Control:**
|
**Code Quality:** Complexity metrics | Duplication | Dead code | Type safety | Best practices | Performance antipatterns
|
||||||
- `--report`: Generate detailed security report
|
|
||||||
- `--json`: Output results in JSON format for automation
|
|
||||||
- `--summary`: Provide executive summary with key findings
|
|
||||||
|
|
||||||
## Examples
|
**Configuration:** Misconfigured services | Insecure defaults | Missing security headers | Exposed endpoints | Weak crypto
|
||||||
- `/scan --validate --quick` → Fast pre-execution safety check
|
|
||||||
- `/scan --security --owasp --comprehensive` → Complete OWASP security audit
|
|
||||||
- `/scan --deps --strict --report` → Dependency scan with detailed report
|
|
||||||
- `/scan --validate --security --think` → Combined validation and security with analysis
|
|
||||||
- `/scan --infrastructure --config --json` → Infrastructure security in JSON format
|
|
||||||
|
|
||||||
## Validation Mode (--validate)
|
## Validation Levels
|
||||||
|
|
||||||
**Pre-Execution Safety Checks:**
|
**Quick (--quick):** Critical security only | Known CVEs | Hardcoded secrets | SQL injection | XSS vulnerabilities
|
||||||
|
|
||||||
**Security Validation:**
|
**Standard (default):** All security checks | Major quality issues | Dependency vulnerabilities | Configuration problems
|
||||||
- Path traversal prevention and boundary enforcement
|
|
||||||
- Secrets and credentials detection in code
|
|
||||||
- Permission verification and access control
|
|
||||||
- Input sanitization and validation checks
|
|
||||||
- Output encoding and XSS prevention
|
|
||||||
|
|
||||||
**Code Validation:**
|
**Strict (--strict):** Everything + minor issues | Style violations | Documentation gaps | Test coverage | Performance warnings
|
||||||
- Syntax correctness and compilation checks
|
|
||||||
- Import and dependency verification
|
|
||||||
- Breaking change detection and compatibility
|
|
||||||
- Configuration validity and completeness
|
|
||||||
- Type safety and null pointer checks
|
|
||||||
|
|
||||||
**Operation Validation:**
|
@include shared/security-patterns.yml#OWASP_Top_10
|
||||||
- Git repository state verification
|
|
||||||
- Branch protection compliance
|
|
||||||
- Resource availability and capacity
|
|
||||||
- Rollback capability assessment
|
|
||||||
- Blast radius and impact analysis
|
|
||||||
|
|
||||||
**Risk Assessment Framework:**
|
|
||||||
- Calculate comprehensive risk score (1-10)
|
|
||||||
- Impact analysis (data loss, downtime, security)
|
|
||||||
- Reversibility and recovery evaluation
|
|
||||||
- Required permissions and access verification
|
|
||||||
- Compliance and regulatory checks
|
|
||||||
|
|
||||||
**Validation Workflow:**
|
|
||||||
1. Parse and analyze intended operation
|
|
||||||
2. Run all applicable safety checks
|
|
||||||
3. Generate risk score and impact assessment
|
|
||||||
4. Report with clear status indicators:
|
|
||||||
- ✅ **Pass**: Safe to proceed without concerns
|
|
||||||
- ⚠️ **Warning**: Caution advised, review recommended
|
|
||||||
- ❌ **Block**: Do not proceed, issues must be resolved
|
|
||||||
|
|
||||||
## Security Mode (--security)
|
|
||||||
|
|
||||||
**OWASP Top 10 Analysis:**
|
|
||||||
- **Injection Flaws**: SQL, NoSQL, OS command, LDAP injection detection
|
|
||||||
- **Broken Authentication**: Session management and auth weakness detection
|
|
||||||
- **Sensitive Data Exposure**: Data protection and encryption analysis
|
|
||||||
- **XML External Entities (XXE)**: XML processing vulnerability detection
|
|
||||||
- **Broken Access Control**: Authorization and privilege escalation issues
|
|
||||||
- **Security Misconfiguration**: Configuration hardening assessment
|
|
||||||
- **Cross-Site Scripting (XSS)**: XSS vulnerability detection and prevention
|
|
||||||
- **Insecure Deserialization**: Object deserialization security analysis
|
|
||||||
- **Known Vulnerable Components**: Dependency vulnerability scanning
|
|
||||||
- **Insufficient Logging**: Security monitoring and audit trail analysis
|
|
||||||
|
|
||||||
**Code Security Analysis:**
|
|
||||||
- Input validation gaps and boundary checks
|
|
||||||
- Output encoding issues and data sanitization
|
|
||||||
- Authentication mechanism weaknesses
|
|
||||||
- Authorization logic flaws and privilege escalation
|
|
||||||
- Cryptographic implementation problems
|
|
||||||
- Error handling information leakage
|
|
||||||
- Session management security issues
|
|
||||||
- File operation safety and path traversal
|
|
||||||
|
|
||||||
**Dependency Security Scanning:**
|
|
||||||
- Known CVE (Common Vulnerabilities and Exposures) detection
|
|
||||||
- Outdated package identification with security implications
|
|
||||||
- License compliance and legal risk assessment
|
|
||||||
- Transitive dependency vulnerability analysis
|
|
||||||
- Security patch availability and update recommendations
|
|
||||||
- Typosquatting and malicious package detection
|
|
||||||
|
|
||||||
**Configuration Security:**
|
|
||||||
- Hardcoded secrets and credentials scanning
|
|
||||||
- Environment variable security assessment
|
|
||||||
- File and directory permission configurations
|
|
||||||
- Network exposure and attack surface analysis
|
|
||||||
- TLS/SSL configuration and certificate validation
|
|
||||||
- CORS policies and cross-origin security
|
|
||||||
- Security headers implementation verification
|
|
||||||
|
|
||||||
**Infrastructure Security:**
|
|
||||||
- Open ports and unnecessary services identification
|
|
||||||
- Firewall rules and network segmentation
|
|
||||||
- Access control lists and identity management
|
|
||||||
- Encryption in transit and at rest verification
|
|
||||||
- Backup security and disaster recovery assessment
|
|
||||||
- Logging configuration and audit trail analysis
|
|
||||||
|
|
||||||
## Scan Execution Modes
|
|
||||||
|
|
||||||
**Quick Scan (--quick):**
|
|
||||||
- Focus on most critical and common vulnerabilities
|
|
||||||
- Skip time-intensive deep analysis procedures
|
|
||||||
- Prioritize immediate security concerns
|
|
||||||
- Provide rapid feedback for development workflow
|
|
||||||
- Suitable for pre-commit hooks and fast CI/CD
|
|
||||||
|
|
||||||
**Comprehensive Scan (--comprehensive):**
|
|
||||||
- Complete security analysis across all categories
|
|
||||||
- Deep dive into complex security patterns
|
|
||||||
- Thorough dependency and configuration analysis
|
|
||||||
- Detailed threat modeling and risk assessment
|
|
||||||
- Suitable for periodic security audits
|
|
||||||
|
|
||||||
**Strict Mode (--strict):**
|
|
||||||
- Zero-tolerance approach to security issues
|
|
||||||
- Flag all potential security concerns
|
|
||||||
- Enforce industry best practices and standards
|
|
||||||
- Require explicit overrides for any findings
|
|
||||||
- Suitable for high-security environments
|
|
||||||
|
|
||||||
## Scan Results and Reporting
|
|
||||||
|
|
||||||
**Security Findings Classification:**
|
|
||||||
- **CRITICAL [10]**: Immediate action required, system at risk
|
|
||||||
- **HIGH [7-9]**: Fix before deployment, significant security risk
|
|
||||||
- **MEDIUM [4-6]**: Address in next development cycle
|
|
||||||
- **LOW [1-3]**: Best practice improvements, technical debt
|
|
||||||
|
|
||||||
**Report Contents:**
|
|
||||||
- Executive summary with overall risk assessment
|
|
||||||
- Detailed findings categorized by security domain
|
|
||||||
- Specific remediation steps with code examples
|
|
||||||
- References to security resources and documentation
|
|
||||||
- Compliance mapping to relevant standards (SOC2, PCI-DSS)
|
|
||||||
- Trend analysis compared to previous scans
|
|
||||||
|
|
||||||
**Integration Behavior:**
|
|
||||||
- Auto-trigger validation for high-risk operations
|
|
||||||
- Chain with execution: `scan --validate && command`
|
|
||||||
- Block execution for CRITICAL [10] severity issues
|
|
||||||
- Require explicit confirmation for HIGH [7-9] risks
|
|
||||||
- Log all scan results for audit and compliance
|
|
||||||
|
|
||||||
## Deliverables
|
## Deliverables
|
||||||
- **Security Report**: Comprehensive vulnerability assessment
|
|
||||||
- **Risk Matrix**: Prioritized list of security issues
|
|
||||||
- **Remediation Guide**: Step-by-step fix instructions
|
|
||||||
- **Compliance Report**: Regulatory and standard compliance status
|
|
||||||
- **Trend Analysis**: Security posture improvement tracking
|
|
||||||
|
|
||||||
## Output Locations
|
**Reports:** `.claudedocs/scans/security-{timestamp}.md` | Severity classification | Fix recommendations | Risk assessment
|
||||||
- **Security Reports**: `.claudedocs/reports/security-scan-{timestamp}.md`
|
|
||||||
- **Validation Results**: `.claudedocs/reports/validation-{timestamp}.md`
|
|
||||||
- **Compliance Reports**: `.claudedocs/reports/compliance-{timestamp}.md`
|
|
||||||
- **Metrics**: `.claudedocs/metrics/security-metrics-{timestamp}.json`
|
|
||||||
|
|
||||||
## Research Requirements
|
**Fix Scripts:** Auto-generated patches | Safe automated fixes | Manual fix instructions | Rollback procedures
|
||||||
External_Library_Research:
|
|
||||||
- Identify library/framework mentioned
|
|
||||||
- Context7 lookup for official documentation
|
|
||||||
- Verify API patterns and examples
|
|
||||||
- Check version compatibility
|
|
||||||
- Document findings in implementation
|
|
||||||
Pattern_Research:
|
|
||||||
- Search existing codebase for similar patterns
|
|
||||||
- Magic component search if UI-related
|
|
||||||
- WebSearch for official documentation
|
|
||||||
- Validate approach with Sequential thinking
|
|
||||||
- Document pattern choice rationale
|
|
||||||
API_Integration_Research:
|
|
||||||
- Official documentation lookup
|
|
||||||
- Authentication requirements
|
|
||||||
- Rate limiting and error handling
|
|
||||||
- SDK availability and examples
|
|
||||||
- Integration testing approach
|
|
||||||
|
|
||||||
## Report Notifications
|
**CI Integration:** Exit codes | JSON output | SARIF format | GitHub/GitLab integration
|
||||||
📄 Analysis report saved to: {path}
|
|
||||||
📊 Metrics updated: {path}
|
|
||||||
📋 Summary saved to: {path}
|
|
||||||
💾 Checkpoint created: {path}
|
|
||||||
📚 Documentation created: {path}
|
|
||||||
📁 Created directory: {path}
|
|
||||||
✅ {operation} completed successfully
|
|
||||||
❌ {operation} failed: {reason}
|
|
||||||
⚠ {operation} completed w/ warnings
|
|
||||||
|
|
||||||
## Integration Patterns
|
@include shared/universal-constants.yml#Success_Messages
|
||||||
|
|
||||||
**CI/CD Integration:**
|
|
||||||
- Fail builds on HIGH or CRITICAL security findings
|
|
||||||
- Generate security reports for each release
|
|
||||||
- Track security debt and improvement trends
|
|
||||||
- Automate security patch application
|
|
||||||
|
|
||||||
**Development Workflow:**
|
|
||||||
- Pre-commit hooks for quick security validation
|
|
||||||
- Pull request security gates
|
|
||||||
- Regular scheduled comprehensive scans
|
|
||||||
- Security review integration with code reviews
|
|
||||||
|
|
||||||
**Command Chaining:**
|
|
||||||
- `scan --validate` before `deploy` operations
|
|
||||||
- `scan --security --strict` for security audits
|
|
||||||
- `scan --deps` before `migrate` operations
|
|
||||||
- `scan --config` after `dev-setup` configuration
|
|
||||||
|
|
||||||
## Best Practices
|
|
||||||
|
|
||||||
**Regular Scanning:**
|
|
||||||
- Run validation before any risky operations
|
|
||||||
- Schedule weekly comprehensive security scans
|
|
||||||
- Implement automated dependency vulnerability monitoring
|
|
||||||
- Track and trend security findings over time
|
|
||||||
|
|
||||||
**Response Procedures:**
|
|
||||||
- Document exceptions with business justification
|
|
||||||
- Implement fix verification with re-scanning
|
|
||||||
- Maintain security issue tracking and resolution
|
|
||||||
- Regular security training and awareness programs
|
|
||||||
|
|
||||||
## Common Security Issues & Solutions
|
|
||||||
|
|
||||||
### SQL Injection Vulnerabilities
|
|
||||||
```bash
|
|
||||||
/scan --security --owasp "SQL injection patterns"
|
|
||||||
# → Identifies unsanitized database queries
|
|
||||||
# → Suggests parameterized query implementations
|
|
||||||
# → Validates input sanitization functions
|
|
||||||
```
|
|
||||||
|
|
||||||
### Dependency Vulnerabilities
|
|
||||||
```bash
|
|
||||||
/scan --deps --security --json
|
|
||||||
# → Scans package.json/requirements.txt for known CVEs
|
|
||||||
# → Provides upgrade paths for vulnerable dependencies
|
|
||||||
# → Generates automated security patch recommendations
|
|
||||||
```
|
|
||||||
|
|
||||||
### Configuration Security Issues
|
|
||||||
```bash
|
|
||||||
/scan --config --env --validate
|
|
||||||
# → Checks for exposed API keys and secrets
|
|
||||||
# → Validates SSL/TLS configuration
|
|
||||||
# → Reviews permission and access control settings
|
|
||||||
```
|
|
||||||
|
|
||||||
### OWASP Top 10 Compliance Check
|
|
||||||
```bash
|
|
||||||
/scan --owasp --comprehensive --report
|
|
||||||
# → Performs full OWASP Top 10 vulnerability assessment
|
|
||||||
# → Generates compliance report with remediation steps
|
|
||||||
# → Tracks progress against security benchmarks
|
|
||||||
```
|
|
||||||
|
|
||||||
## Troubleshooting
|
|
||||||
- **False Positives**: Use `--quick` for initial assessment, then `--comprehensive`
|
|
||||||
- **Complex Applications**: Apply `--think-hard` for thorough analysis
|
|
||||||
- **CI/CD Integration**: Use `--json` output for automated processing
|
|
||||||
- **Legacy Systems**: Combine `--security --deps --config` for complete assessment
|
|
||||||
|
|
||||||
## Success Messages
|
|
||||||
✅ {operation} completed successfully
|
|
||||||
📝 Created: {file_path}
|
|
||||||
✏ Updated: {file_path}
|
|
||||||
✨ Task completed: {task_title}
|
|
||||||
@@ -14,6 +14,31 @@ Command_Header:
|
|||||||
Legend: "@cmd-specific legend gen"
|
Legend: "@cmd-specific legend gen"
|
||||||
Purpose: "[Action][Subject] in $ARGUMENTS"
|
Purpose: "[Action][Subject] in $ARGUMENTS"
|
||||||
|
|
||||||
|
## Optimized Command File Template
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
# Standard template for all command files using @include references
|
||||||
|
Optimized_Command_Template: |
|
||||||
|
@include shared/universal-constants.yml#Universal_Legend
|
||||||
|
|
||||||
|
## Command Execution
|
||||||
|
Execute: immediate. --plan→show plan first
|
||||||
|
Legend: Generated based on symbols used in command
|
||||||
|
Purpose: "[Action][Subject] in $ARGUMENTS"
|
||||||
|
|
||||||
|
[Command-specific description here]
|
||||||
|
|
||||||
|
@include shared/flag-inheritance.yml#Universal_Always
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
- `/{command} --flag` - Description
|
||||||
|
- `/{command} --other-flag` - Description
|
||||||
|
- `/{command} --complex-example` - Description
|
||||||
|
|
||||||
|
[Command-specific content sections]
|
||||||
|
|
||||||
|
@include shared/universal-constants.yml#Success_Messages
|
||||||
|
|
||||||
## UltraCompressed Command Structure
|
## UltraCompressed Command Structure
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
|
|||||||
@@ -1,38 +1,7 @@
|
|||||||
# /spawn - Spawn focused agent for specialized tasks
|
# /spawn - Spawn focused agent for specialized tasks
|
||||||
|
|
||||||
## Legend
|
## Legend
|
||||||
| Symbol | Meaning | | Abbrev | Meaning |
|
@include shared/universal-constants.yml#Universal_Legend
|
||||||
|--------|---------|---|--------|---------|
|
|
||||||
| → | leads to | | cfg | configuration |
|
|
||||||
| & | and/with | | impl | implementation |
|
|
||||||
| w/ | with | | perf | performance |
|
|
||||||
| @ | at/located | | ops | operations |
|
|
||||||
| > | greater than | | val | validation |
|
|
||||||
| ∀ | for all/every | | req | requirements |
|
|
||||||
| ∃ | exists/there is | | deps | dependencies |
|
|
||||||
| ∴ | therefore | | env | environment |
|
|
||||||
| ∵ | because | | db | database |
|
|
||||||
| ≡ | equivalent | | api | interface |
|
|
||||||
| ≈ | approximately | | docs | documentation |
|
|
||||||
| 📁 | directory/path | | std | standard |
|
|
||||||
| 🔢 | number/count | | def | default |
|
|
||||||
| 📝 | text/string | | ctx | context |
|
|
||||||
| ⚙ | setting/config | | err | error |
|
|
||||||
| 🎛 | control/flags | | exec | execution |
|
|
||||||
| 🔧 | configuration | | qual | quality |
|
|
||||||
| 📋 | group/category | | rec | recovery |
|
|
||||||
| 🚨 | critical/urgent | | sev | severity |
|
|
||||||
| ⚠ | warning/caution | | resp | response |
|
|
||||||
| 🔄 | retry/recovery | | esc | escalation |
|
|
||||||
| ✅ | success/fixed | | tok | token |
|
|
||||||
| ❌ | failure/error | | opt | optimization |
|
|
||||||
| ℹ | information | | UX | user experience |
|
|
||||||
| ⚡ | fast/quick | | UI | user interface |
|
|
||||||
| 🐌 | slow/delayed | | C | critical |
|
|
||||||
| ✨ | complete/done | | H | high |
|
|
||||||
| 📖 | read operation | | M | medium |
|
|
||||||
| ✏ | edit operation | | L | low |
|
|
||||||
| 🗑 | delete operation | | |
|
|
||||||
|
|
||||||
## Purpose
|
## Purpose
|
||||||
Spawn specialized sub-agents to handle specific tasks in $ARGUMENTS with focused expertise and parallel execution capabilities.
|
Spawn specialized sub-agents to handle specific tasks in $ARGUMENTS with focused expertise and parallel execution capabilities.
|
||||||
@@ -40,272 +9,143 @@ Spawn specialized sub-agents to handle specific tasks in $ARGUMENTS with focused
|
|||||||
## Syntax
|
## Syntax
|
||||||
`/spawn [flags] [task-description]`
|
`/spawn [flags] [task-description]`
|
||||||
|
|
||||||
## Universal Flags
|
@include shared/flag-inheritance.yml#Universal_Always
|
||||||
--plan: "Show execution plan before running"
|
|
||||||
--uc: "UltraCompressed mode (~70% token reduction)"
|
|
||||||
--ultracompressed: "Alias for --uc"
|
|
||||||
--think: "Multi-file analysis w/ context (4K tokens)"
|
|
||||||
--think-hard: "Deep architectural analysis (10K tokens)"
|
|
||||||
--ultrathink: "Critical system redesign (32K tokens)"
|
|
||||||
--c7: "Enable Context7→library documentation lookup"
|
|
||||||
--seq: "Enable Sequential→complex analysis & thinking"
|
|
||||||
--magic: "Enable Magic→UI component generation"
|
|
||||||
--pup: "Enable Puppeteer→browser automation & testing"
|
|
||||||
--all-mcp: "Enable all MCP servers"
|
|
||||||
--no-mcp: "Disable all MCP servers (native tools only)"
|
|
||||||
--no-c7: "Disable Context7 specifically"
|
|
||||||
--no-seq: "Disable Sequential thinking specifically"
|
|
||||||
--no-magic: "Disable Magic UI builder specifically"
|
|
||||||
--no-pup: "Disable Puppeteer specifically"
|
|
||||||
|
|
||||||
## Command-Specific Flags
|
## Core Flags
|
||||||
|
|
||||||
**Agent Specialization:**
|
--agent flag:
|
||||||
- `--frontend`: Spawn UI/UX and frontend development agent
|
- researcher: Deep research & analysis
|
||||||
- `--backend`: Spawn API and backend services agent
|
- builder: Code generation
|
||||||
- `--devops`: Spawn infrastructure and deployment agent
|
- reviewer: Code review & QA
|
||||||
- `--data`: Spawn data analysis and database agent
|
- optimizer: Performance tuning
|
||||||
- `--security`: Spawn security and compliance agent
|
- documenter: Documentation expert
|
||||||
- `--qa`: Spawn quality assurance and testing agent
|
|
||||||
|
|
||||||
**Task Configuration:**
|
--mode flag:
|
||||||
- `--task [description]`: Define clear, focused assignment with specific objectives
|
- sequential: One agent at a time
|
||||||
- `--context [info]`: Provide necessary background context and constraints
|
- parallel: Multiple agents
|
||||||
- `--scope [boundaries]`: Set clear task boundaries and limitations
|
- collaborative: Agents work together
|
||||||
- `--timeline [duration]`: Specify expected completion timeframe
|
- supervisor: Oversee sub-agents
|
||||||
|
|
||||||
**Coordination:**
|
--scope flag:
|
||||||
- `--parallel`: Enable parallel execution with main workflow
|
- focused: Single specific task
|
||||||
- `--sequential`: Require sequential execution after current tasks
|
- broad: Multiple related tasks
|
||||||
- `--integrate`: Automatic integration of results with main context
|
- exploratory: Open-ended research
|
||||||
- `--review`: Require manual review before integration
|
- iterative: Refine through cycles
|
||||||
|
|
||||||
**Quality Control:**
|
## Agent Types
|
||||||
- `--validate`: Validate agent output before integration
|
|
||||||
- `--test`: Include testing requirements in agent task
|
|
||||||
- `--document`: Require documentation of agent work
|
|
||||||
|
|
||||||
## Examples
|
Researcher Agent:
|
||||||
- `/spawn --frontend --task "implement user dashboard" --think` → Frontend agent with coordination analysis
|
- Deep dive into topics
|
||||||
- `/spawn --security --task "implement auth system" --validate --think-hard` → Security agent with validation
|
- Compare solutions
|
||||||
- `/spawn --devops --task "setup CI/CD pipeline" --document --ultrathink` → DevOps agent with documentation
|
- Analyze trade-offs
|
||||||
- `/spawn --data --task "optimize database queries" --test --parallel` → Data agent with testing in parallel
|
- Find best practices
|
||||||
- `/spawn --qa --task "comprehensive test suite" --integrate` → QA agent with auto-integration
|
- Document findings
|
||||||
|
|
||||||
## Agent Specializations
|
Builder Agent:
|
||||||
|
- Generate code
|
||||||
|
- Implement features
|
||||||
|
- Create tests
|
||||||
|
- Build prototypes
|
||||||
|
- Integrate systems
|
||||||
|
|
||||||
**Frontend Agent:**
|
Reviewer Agent:
|
||||||
- User interface and user experience implementation
|
- Code quality checks
|
||||||
- Component development with modern frameworks
|
- Security analysis
|
||||||
- State management and data flow
|
- Performance review
|
||||||
- Performance optimization and bundle analysis
|
- Best practice validation
|
||||||
- Accessibility compliance and responsive design
|
- Suggest improvements
|
||||||
- Cross-browser compatibility and testing
|
|
||||||
|
|
||||||
**Backend Agent:**
|
Optimizer Agent:
|
||||||
- RESTful and GraphQL API development
|
- Performance profiling
|
||||||
- Database design and operations
|
- Resource optimization
|
||||||
- Business logic implementation
|
- Algorithm improvements
|
||||||
- Third-party service integrations
|
- Database tuning
|
||||||
- Performance tuning and optimization
|
- Cache strategies
|
||||||
- Security implementation and hardening
|
|
||||||
|
|
||||||
**DevOps Agent:**
|
Documenter Agent:
|
||||||
- CI/CD pipeline setup and optimization
|
- API documentation
|
||||||
- Infrastructure as Code (IaC) development
|
- User guides
|
||||||
- Deployment strategy design and implementation
|
- Code comments
|
||||||
- Monitoring and observability configuration
|
- Architecture docs
|
||||||
- Security hardening and compliance
|
- README files
|
||||||
- Container orchestration and scaling
|
|
||||||
|
|
||||||
**Data Agent:**
|
## Execution Modes
|
||||||
- Data analysis and statistical modeling
|
|
||||||
- Database optimization and query tuning
|
|
||||||
- ETL pipeline development and maintenance
|
|
||||||
- Data quality assurance and validation
|
|
||||||
- Reporting and visualization solutions
|
|
||||||
- Data governance and compliance
|
|
||||||
|
|
||||||
**Security Agent:**
|
Sequential Mode:
|
||||||
- Security vulnerability assessment and remediation
|
```yaml
|
||||||
- Authentication and authorization implementation
|
Flow: Agent1 → Agent2 → Agent3
|
||||||
- Encryption and data protection strategies
|
Use: When tasks depend on each other
|
||||||
- Compliance framework implementation
|
Example: Research → Build → Review
|
||||||
- Security monitoring and incident response
|
```
|
||||||
- Penetration testing and security audits
|
|
||||||
|
|
||||||
**QA Agent:**
|
Parallel Mode:
|
||||||
- Test strategy and framework development
|
```yaml
|
||||||
- Automated testing implementation
|
Flow: Agent1 | Agent2 | Agent3
|
||||||
- Manual testing procedures and protocols
|
Use: For independent tasks
|
||||||
- Performance and load testing
|
Example: Multiple feature builds
|
||||||
- Quality metrics and reporting
|
```
|
||||||
- Bug tracking and resolution workflows
|
|
||||||
|
|
||||||
## Agent Task Definition
|
Collaborative Mode:
|
||||||
|
```yaml
|
||||||
**Clear Scope Definition:**
|
Flow: Agents work together
|
||||||
- Specific, measurable deliverables
|
Use: Complex problems
|
||||||
- Clear task boundaries and limitations
|
Example: System design session
|
||||||
- Time constraints and deadlines
|
```
|
||||||
- Quality expectations and standards
|
|
||||||
- Success criteria and acceptance conditions
|
|
||||||
|
|
||||||
**Context Provision:**
|
|
||||||
- Relevant code sections and documentation
|
|
||||||
- Architecture decisions and constraints
|
|
||||||
- Previous implementation decisions
|
|
||||||
- Technical requirements and dependencies
|
|
||||||
- Integration points with existing systems
|
|
||||||
|
|
||||||
**Success Criteria:**
|
|
||||||
- Measurable outcomes and metrics
|
|
||||||
- Quality standards and benchmarks
|
|
||||||
- Integration requirements and compatibility
|
|
||||||
- Testing expectations and coverage
|
|
||||||
- Performance targets and constraints
|
|
||||||
|
|
||||||
**Coordination Requirements:**
|
|
||||||
- Avoid conflicts with ongoing work
|
|
||||||
- Plan integration and merge points
|
|
||||||
- Handle inter-task dependencies
|
|
||||||
- Manage communication and updates
|
|
||||||
- Establish review and approval processes
|
|
||||||
|
|
||||||
## Agent Workflow
|
|
||||||
|
|
||||||
**1. Agent Spawning:**
|
|
||||||
- Analyze task requirements and complexity
|
|
||||||
- Select appropriate agent specialization
|
|
||||||
- Define clear task scope and objectives
|
|
||||||
- Provide necessary context and constraints
|
|
||||||
- Establish success criteria and timeline
|
|
||||||
|
|
||||||
**2. Independent Execution:**
|
|
||||||
- Agent works autonomously on assigned task
|
|
||||||
- Focused context and specialized expertise
|
|
||||||
- Progress tracking and status updates
|
|
||||||
- Problem-solving within defined scope
|
|
||||||
- Quality assurance and self-validation
|
|
||||||
|
|
||||||
**3. Progress Monitoring:**
|
|
||||||
- Regular status updates and checkpoints
|
|
||||||
- Issue escalation and dependency resolution
|
|
||||||
- Scope adjustment and timeline management
|
|
||||||
- Quality review and feedback incorporation
|
|
||||||
- Communication with main workflow
|
|
||||||
|
|
||||||
**4. Result Integration:**
|
|
||||||
- Comprehensive result review and validation
|
|
||||||
- Integration planning and execution
|
|
||||||
- Knowledge transfer to main context
|
|
||||||
- Documentation and lessons learned
|
|
||||||
- Quality verification and testing
|
|
||||||
|
|
||||||
**5. Completion Handoff:**
|
|
||||||
- Final deliverable validation
|
|
||||||
- Integration verification and testing
|
|
||||||
- Documentation and knowledge transfer
|
|
||||||
- Cleanup and resource management
|
|
||||||
- Success metrics and outcome assessment
|
|
||||||
|
|
||||||
## Benefits of Agent Spawning
|
|
||||||
|
|
||||||
**Efficiency Gains:**
|
|
||||||
- Parallel task execution and processing
|
|
||||||
- Specialized expertise and focused attention
|
|
||||||
- Reduced cognitive load on main workflow
|
|
||||||
- Faster task completion and delivery
|
|
||||||
- Improved resource utilization
|
|
||||||
|
|
||||||
**Quality Improvements:**
|
|
||||||
- Domain-specific expertise application
|
|
||||||
- Focused quality assurance and testing
|
|
||||||
- Specialized best practices implementation
|
|
||||||
- Reduced context switching overhead
|
|
||||||
- Enhanced problem-solving capabilities
|
|
||||||
|
|
||||||
**Scalability Advantages:**
|
|
||||||
- Distributed workload management
|
|
||||||
- Independent task scaling
|
|
||||||
- Flexible resource allocation
|
|
||||||
- Modular development approach
|
|
||||||
- Improved development velocity
|
|
||||||
|
|
||||||
## Deliverables
|
|
||||||
- **Task Results**: Completed work from spawned agent with quality validation
|
|
||||||
- **Integration Plan**: Strategy for merging agent work with main context
|
|
||||||
- **Knowledge Transfer**: Documentation of agent decisions and implementation
|
|
||||||
- **Coordination Summary**: Agent workflow and communication log
|
|
||||||
- **Quality Report**: Validation and testing results from agent work
|
|
||||||
|
|
||||||
## Output Locations
|
|
||||||
- **Agent Logs**: `.claudedocs/reports/agent-spawn-{timestamp}.md`
|
|
||||||
- **Task Results**: `.claudedocs/summaries/agent-results-{timestamp}.md`
|
|
||||||
- **Integration Plans**: `.claudedocs/summaries/integration-plan-{timestamp}.md`
|
|
||||||
|
|
||||||
## Research Requirements
|
|
||||||
External_Library_Research:
|
|
||||||
- Identify library/framework mentioned
|
|
||||||
- Context7 lookup for official documentation
|
|
||||||
- Verify API patterns and examples
|
|
||||||
- Check version compatibility
|
|
||||||
- Document findings in implementation
|
|
||||||
Pattern_Research:
|
|
||||||
- Search existing codebase for similar patterns
|
|
||||||
- Magic component search if UI-related
|
|
||||||
- WebSearch for official documentation
|
|
||||||
- Validate approach with Sequential thinking
|
|
||||||
- Document pattern choice rationale
|
|
||||||
API_Integration_Research:
|
|
||||||
- Official documentation lookup
|
|
||||||
- Authentication requirements
|
|
||||||
- Rate limiting and error handling
|
|
||||||
- SDK availability and examples
|
|
||||||
- Integration testing approach
|
|
||||||
|
|
||||||
## Report Notifications
|
|
||||||
📄 Analysis report saved to: {path}
|
|
||||||
📊 Metrics updated: {path}
|
|
||||||
📋 Summary saved to: {path}
|
|
||||||
💾 Checkpoint created: {path}
|
|
||||||
📚 Documentation created: {path}
|
|
||||||
📁 Created directory: {path}
|
|
||||||
✅ {operation} completed successfully
|
|
||||||
❌ {operation} failed: {reason}
|
|
||||||
⚠ {operation} completed w/ warnings
|
|
||||||
|
|
||||||
## Best Practices
|
## Best Practices
|
||||||
|
|
||||||
**Agent Management:**
|
Task Definition:
|
||||||
- Define clear, specific task objectives
|
- Clear objectives
|
||||||
- Provide comprehensive context and constraints
|
- Specific deliverables
|
||||||
- Establish measurable success criteria
|
- Success criteria
|
||||||
- Plan integration points and dependencies
|
- Resource limits
|
||||||
- Monitor progress and provide feedback
|
- Time constraints
|
||||||
|
|
||||||
**Quality Assurance:**
|
Agent Selection:
|
||||||
- Validate agent output before integration
|
- Match expertise to task
|
||||||
- Test agent deliverables thoroughly
|
- Consider dependencies
|
||||||
- Review code quality and standards compliance
|
- Plan coordination
|
||||||
- Verify documentation completeness
|
- Set boundaries
|
||||||
- Assess performance and security implications
|
- Define handoffs
|
||||||
|
|
||||||
**Coordination:**
|
Coordination:
|
||||||
- Avoid task overlap and conflicts
|
- Clear communication
|
||||||
- Manage dependencies and prerequisites
|
- Shared context
|
||||||
- Maintain clear communication channels
|
- Progress tracking
|
||||||
- Handle scope changes and adjustments
|
- Result integration
|
||||||
- Ensure knowledge transfer and documentation
|
- Quality control
|
||||||
|
|
||||||
## Troubleshooting
|
## Examples
|
||||||
- **Complex Tasks**: Use `--think-hard` for comprehensive planning
|
|
||||||
- **Integration Issues**: Apply `--review --validate` for quality control
|
|
||||||
- **Parallel Execution**: Use `--parallel --coordinate` for workflow management
|
|
||||||
- **Quality Concerns**: Combine `--qa --test --document` for thorough validation
|
|
||||||
|
|
||||||
## Success Messages
|
```bash
|
||||||
✅ {operation} completed successfully
|
# Research then implement
|
||||||
📝 Created: {file_path}
|
/spawn --agent researcher "OAuth 2.0 best practices"
|
||||||
✏ Updated: {file_path}
|
/spawn --agent builder "Implement OAuth based on research"
|
||||||
✨ Task completed: {task_title}
|
|
||||||
|
# Parallel feature development
|
||||||
|
/spawn --mode parallel --agent builder "User auth, Profile API, Settings UI"
|
||||||
|
|
||||||
|
# Full cycle with review
|
||||||
|
/spawn --mode sequential "Research → Build → Review payment integration"
|
||||||
|
|
||||||
|
# Collaborative system design
|
||||||
|
/spawn --mode collaborative --ultrathink "Design microservices architecture"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Integration
|
||||||
|
|
||||||
|
Works with:
|
||||||
|
- All command flags pass through
|
||||||
|
- Inherits persona preferences
|
||||||
|
- Shares project context
|
||||||
|
- Accumulates findings
|
||||||
|
- Coordinates outputs
|
||||||
|
|
||||||
|
## Deliverables
|
||||||
|
|
||||||
|
- Agent execution logs
|
||||||
|
- Task completion reports
|
||||||
|
- Integrated results
|
||||||
|
- Performance metrics
|
||||||
|
- Lessons learned
|
||||||
|
- Handoff documentation
|
||||||
@@ -1,38 +1,7 @@
|
|||||||
# /task - Manage complex features and requirements
|
# /task - Manage complex features and requirements
|
||||||
|
|
||||||
## Legend
|
## Legend
|
||||||
| Symbol | Meaning | | Abbrev | Meaning |
|
@include shared/universal-constants.yml#Universal_Legend
|
||||||
|--------|---------|---|--------|---------|
|
|
||||||
| → | leads to | | cfg | configuration |
|
|
||||||
| & | and/with | | impl | implementation |
|
|
||||||
| w/ | with | | perf | performance |
|
|
||||||
| @ | at/located | | ops | operations |
|
|
||||||
| > | greater than | | val | validation |
|
|
||||||
| ∀ | for all/every | | req | requirements |
|
|
||||||
| ∃ | exists/there is | | deps | dependencies |
|
|
||||||
| ∴ | therefore | | env | environment |
|
|
||||||
| ∵ | because | | db | database |
|
|
||||||
| ≡ | equivalent | | api | interface |
|
|
||||||
| ≈ | approximately | | docs | documentation |
|
|
||||||
| 📁 | directory/path | | std | standard |
|
|
||||||
| 🔢 | number/count | | def | default |
|
|
||||||
| 📝 | text/string | | ctx | context |
|
|
||||||
| ⚙ | setting/config | | err | error |
|
|
||||||
| 🎛 | control/flags | | exec | execution |
|
|
||||||
| 🔧 | configuration | | qual | quality |
|
|
||||||
| 📋 | group/category | | rec | recovery |
|
|
||||||
| 🚨 | critical/urgent | | sev | severity |
|
|
||||||
| ⚠ | warning/caution | | resp | response |
|
|
||||||
| 🔄 | retry/recovery | | esc | escalation |
|
|
||||||
| ✅ | success/fixed | | tok | token |
|
|
||||||
| ❌ | failure/error | | opt | optimization |
|
|
||||||
| ℹ | information | | UX | user experience |
|
|
||||||
| ⚡ | fast/quick | | UI | user interface |
|
|
||||||
| 🐌 | slow/delayed | | C | critical |
|
|
||||||
| ✨ | complete/done | | H | high |
|
|
||||||
| 📖 | read operation | | M | medium |
|
|
||||||
| ✏ | edit operation | | L | low |
|
|
||||||
| 🗑 | delete operation | | |
|
|
||||||
|
|
||||||
## Purpose
|
## Purpose
|
||||||
Manage complex features and requirements across sessions with automatic breakdown, context preservation, and recovery capabilities.
|
Manage complex features and requirements across sessions with automatic breakdown, context preservation, and recovery capabilities.
|
||||||
@@ -40,271 +9,135 @@ Manage complex features and requirements across sessions with automatic breakdow
|
|||||||
## Syntax
|
## Syntax
|
||||||
`/task [operation] [parameters]`
|
`/task [operation] [parameters]`
|
||||||
|
|
||||||
## Universal Flags
|
@include shared/flag-inheritance.yml#Universal_Always
|
||||||
--plan: "Show execution plan before running"
|
|
||||||
--uc: "UltraCompressed mode (~70% token reduction)"
|
|
||||||
--ultracompressed: "Alias for --uc"
|
|
||||||
--think: "Multi-file analysis w/ context (4K tokens)"
|
|
||||||
--think-hard: "Deep architectural analysis (10K tokens)"
|
|
||||||
--ultrathink: "Critical system redesign (32K tokens)"
|
|
||||||
--c7: "Enable Context7→library documentation lookup"
|
|
||||||
--seq: "Enable Sequential→complex analysis & thinking"
|
|
||||||
--magic: "Enable Magic→UI component generation"
|
|
||||||
--pup: "Enable Puppeteer→browser automation & testing"
|
|
||||||
--all-mcp: "Enable all MCP servers"
|
|
||||||
--no-mcp: "Disable all MCP servers (native tools only)"
|
|
||||||
--no-c7: "Disable Context7 specifically"
|
|
||||||
--no-seq: "Disable Sequential thinking specifically"
|
|
||||||
--no-magic: "Disable Magic UI builder specifically"
|
|
||||||
--no-pup: "Disable Puppeteer specifically"
|
|
||||||
|
|
||||||
## Command-Specific Operations
|
## Operations
|
||||||
|
|
||||||
**Task Operations:**
|
/task:create [description]:
|
||||||
- `create <title>`: Create new task with automatic breakdown
|
- Create new task with automatic breakdown
|
||||||
- `list`: Show tasks filtered by status or priority
|
- Generate subtasks & milestones
|
||||||
- `start <id>`: Begin working on specific task
|
- Set up tracking structure
|
||||||
- `pause <id>`: Pause current work and save context
|
- Initialize context preservation
|
||||||
- `resume <id>`: Resume previously paused task
|
|
||||||
- `complete <id>`: Mark task as completed with verification
|
|
||||||
- `cancel <id>`: Cancel task and clean up resources
|
|
||||||
- `show <id>`: Display detailed task information
|
|
||||||
- `update <id>`: Modify task status, priority, or details
|
|
||||||
|
|
||||||
**Task Types:**
|
/task:update [task-id] [updates]:
|
||||||
- `--type feature`: New feature development
|
- Update task progress
|
||||||
- `--type bugfix`: Bug resolution and fixes
|
- Modify requirements
|
||||||
- `--type refactor`: Code refactoring and improvement
|
- Adjust timeline
|
||||||
- `--type docs`: Documentation creation or updates
|
- Add discoveries
|
||||||
- `--type test`: Testing implementation or enhancement
|
|
||||||
|
|
||||||
**Priority Levels:**
|
/task:status [task-id]:
|
||||||
- `--priority high`: Critical or urgent tasks
|
- Show current progress
|
||||||
- `--priority medium`: Standard priority tasks (default)
|
- List completed subtasks
|
||||||
- `--priority low`: Nice-to-have or future enhancements
|
- Display blockers
|
||||||
|
- Estimate remaining work
|
||||||
|
|
||||||
**Status Filters:**
|
/task:resume [task-id]:
|
||||||
- `--status pending`: Tasks waiting to be started
|
- Load task context
|
||||||
- `--status in-progress`: Currently active tasks
|
- Continue from last point
|
||||||
- `--status completed`: Finished tasks
|
- Restore working state
|
||||||
- `--status cancelled`: Cancelled or abandoned tasks
|
- Update progress
|
||||||
|
|
||||||
## Examples
|
/task:complete [task-id]:
|
||||||
- `/task create "User authentication system" --type feature --priority high`
|
- Mark task as done
|
||||||
- `/task list --status pending --priority high`
|
- Generate summary
|
||||||
- `/task start 20250623-143052`
|
- Archive artifacts
|
||||||
- `/task pause 20250623-143052`
|
- Create documentation
|
||||||
- `/task resume 20250623-143052`
|
|
||||||
- `/task complete 20250623-143052`
|
|
||||||
- `/task show 20250623-143052`
|
|
||||||
- `/task update 20250623-143052 --priority low`
|
|
||||||
|
|
||||||
## Task Workflow
|
## Task Structure
|
||||||
|
|
||||||
**Task Creation:**
|
@include shared/task-patterns.yml#Task_Structure
|
||||||
1. **Requirement Analysis**: Analyze complexity and scope
|
|
||||||
2. **ID Generation**: Create unique task ID (YYYYMMDD-HHMMSS)
|
|
||||||
3. **Breakdown**: Decompose into phases and actionable steps
|
|
||||||
4. **File Creation**: Generate task file from appropriate template
|
|
||||||
5. **Git Integration**: Create dedicated branch for task
|
|
||||||
6. **Organization**: Move to pending folder for tracking
|
|
||||||
|
|
||||||
**Task Execution:**
|
Task Components:
|
||||||
1. **Activation**: Move task to in-progress folder
|
- Title & description
|
||||||
2. **Checkpoint**: Create git checkpoint for safety
|
- Acceptance criteria
|
||||||
3. **Sequential Execution**: Work through steps systematically
|
- Technical requirements
|
||||||
4. **Progress Tracking**: Update progress and context continuously
|
- Subtask breakdown
|
||||||
5. **Session Management**: Handle interruptions and breaks gracefully
|
- Progress tracking
|
||||||
|
- Context preservation
|
||||||
|
|
||||||
**Task Completion:**
|
## Automatic Features
|
||||||
1. **Verification**: Ensure all steps completed successfully
|
|
||||||
2. **Testing**: Run comprehensive tests and validation
|
|
||||||
3. **Checkpoint**: Create completion checkpoint
|
|
||||||
4. **Organization**: Move to completed folder
|
|
||||||
5. **Integration**: Merge git branch and clean up
|
|
||||||
|
|
||||||
## Auto-Detection
|
Smart Breakdown:
|
||||||
|
- Analyze complexity
|
||||||
|
- Create subtasks
|
||||||
|
- Identify dependencies
|
||||||
|
- Estimate effort
|
||||||
|
- Set milestones
|
||||||
|
|
||||||
**Complexity Triggers:**
|
Context Preservation:
|
||||||
- "build feature X" or "implement functionality Y"
|
- Save working state
|
||||||
- "add component Z" or "create system W"
|
- Track decisions
|
||||||
- Requirements affecting more than 3 files
|
- Store code changes
|
||||||
- Multi-step work requiring coordination
|
- Maintain history
|
||||||
- Complex integration or architectural changes
|
- Enable recovery
|
||||||
|
|
||||||
**System Response:**
|
Progress Tracking:
|
||||||
- Analyze request complexity automatically
|
- Update automatically
|
||||||
- Suggest task creation for complex work
|
- Track blockers
|
||||||
- Provide options: [Create task breakdown] [Proceed directly]
|
- Monitor velocity
|
||||||
- Explain benefits of task management approach
|
- Adjust estimates
|
||||||
- Respect user preference for simple tasks
|
- Report status
|
||||||
|
|
||||||
## Session Recovery
|
## Recovery System
|
||||||
|
|
||||||
**Startup Process:**
|
@include shared/session-recovery.yml#Recovery_Patterns
|
||||||
1. **Scan**: Check `.claudedocs/tasks/in-progress/` directory
|
|
||||||
2. **Identify**: Find active tasks and their current state
|
|
||||||
3. **Restore**: Load context from task files and git history
|
|
||||||
4. **Suggest**: Recommend next steps for resumption
|
|
||||||
|
|
||||||
**Context Preservation:**
|
Session Recovery:
|
||||||
- Key architectural decisions and rationale
|
- Auto-detect incomplete tasks
|
||||||
- Current implementation state and progress
|
- Load previous context
|
||||||
- Known blockers and proposed solutions
|
- Resume from checkpoint
|
||||||
- File modification history and dependencies
|
- Maintain continuity
|
||||||
- Integration points and testing requirements
|
- Preserve momentum
|
||||||
|
|
||||||
## Task File Structure
|
|
||||||
|
|
||||||
**Directory Organization:**
|
|
||||||
```
|
|
||||||
.claudedocs/tasks/
|
|
||||||
├── pending/ # Tasks waiting to be started
|
|
||||||
├── in-progress/ # Currently active tasks
|
|
||||||
├── completed/ # Finished tasks
|
|
||||||
├── cancelled/ # Cancelled or abandoned tasks
|
|
||||||
└── templates/ # Task templates by type
|
|
||||||
```
|
|
||||||
|
|
||||||
**File Naming Convention:**
|
|
||||||
```
|
|
||||||
{type}-{id}-{slug}.md
|
|
||||||
|
|
||||||
Examples:
|
|
||||||
feature-20250623-143052-user-auth.md
|
|
||||||
bugfix-20250623-144022-login-error.md
|
|
||||||
refactor-20250623-142033-api-cleanup.md
|
|
||||||
```
|
|
||||||
|
|
||||||
**Task File Content:**
|
|
||||||
- Task metadata (ID, type, priority, status)
|
|
||||||
- Detailed description and requirements
|
|
||||||
- Phase breakdown with progress tracking
|
|
||||||
- Context and architectural decisions
|
|
||||||
- Blockers and resolution strategies
|
|
||||||
- Testing and validation requirements
|
|
||||||
|
|
||||||
## Integration Capabilities
|
|
||||||
|
|
||||||
**Git Integration:**
|
|
||||||
- Automatic branch creation and management
|
|
||||||
- Checkpoint creation for safety and rollback
|
|
||||||
- Merge strategy and conflict resolution
|
|
||||||
- Commit message generation and conventions
|
|
||||||
|
|
||||||
**TodoWrite Synchronization:**
|
|
||||||
- Sync with existing todo system
|
|
||||||
- Convert todos to tasks when appropriate
|
|
||||||
- Maintain consistency across systems
|
|
||||||
- Provide unified task management experience
|
|
||||||
|
|
||||||
**Persona Activation:**
|
|
||||||
- Task-specific persona selection
|
|
||||||
- Specialized expertise for different task types
|
|
||||||
- Context-aware skill application
|
|
||||||
- Collaborative persona workflows
|
|
||||||
|
|
||||||
**MCP Integration:**
|
|
||||||
- Context preservation across MCP tools
|
|
||||||
- State management for complex operations
|
|
||||||
- Tool coordination for task execution
|
|
||||||
- Resource optimization and sharing
|
|
||||||
|
|
||||||
**Command Chaining:**
|
|
||||||
- Chain with other SuperClaude commands
|
|
||||||
- Workflow automation and optimization
|
|
||||||
- Cross-command context sharing
|
|
||||||
- Integrated development experience
|
|
||||||
|
|
||||||
## Advanced Features
|
|
||||||
|
|
||||||
**Task Dependencies:**
|
|
||||||
- Define prerequisite relationships
|
|
||||||
- Automatic dependency resolution
|
|
||||||
- Blocked task identification
|
|
||||||
- Parallel execution planning
|
|
||||||
|
|
||||||
**Progress Tracking:**
|
|
||||||
- Phase-based progress measurement
|
|
||||||
- Milestone tracking and reporting
|
|
||||||
- Time estimation and actual tracking
|
|
||||||
- Velocity and performance metrics
|
|
||||||
|
|
||||||
**Collaboration Support:**
|
|
||||||
- Multi-contributor task support
|
|
||||||
- Handoff procedures and documentation
|
|
||||||
- Knowledge transfer mechanisms
|
|
||||||
- Team coordination features
|
|
||||||
|
|
||||||
## Deliverables
|
|
||||||
- **Task Files**: Comprehensive task documentation with progress tracking
|
|
||||||
- **Git Branches**: Dedicated branches with checkpoint history
|
|
||||||
- **Progress Reports**: Regular status updates and metrics
|
|
||||||
- **Context Documentation**: Preserved decision-making rationale
|
|
||||||
- **Integration Plans**: Merge and deployment strategies
|
|
||||||
|
|
||||||
## Research Requirements
|
|
||||||
External_Library_Research:
|
|
||||||
- Identify library/framework mentioned
|
|
||||||
- Context7 lookup for official documentation
|
|
||||||
- Verify API patterns and examples
|
|
||||||
- Check version compatibility
|
|
||||||
- Document findings in implementation
|
|
||||||
Pattern_Research:
|
|
||||||
- Search existing codebase for similar patterns
|
|
||||||
- Magic component search if UI-related
|
|
||||||
- WebSearch for official documentation
|
|
||||||
- Validate approach with Sequential thinking
|
|
||||||
- Document pattern choice rationale
|
|
||||||
API_Integration_Research:
|
|
||||||
- Official documentation lookup
|
|
||||||
- Authentication requirements
|
|
||||||
- Rate limiting and error handling
|
|
||||||
- SDK availability and examples
|
|
||||||
- Integration testing approach
|
|
||||||
|
|
||||||
## Report Notifications
|
|
||||||
📄 Analysis report saved to: {path}
|
|
||||||
📊 Metrics updated: {path}
|
|
||||||
📋 Summary saved to: {path}
|
|
||||||
💾 Checkpoint created: {path}
|
|
||||||
📚 Documentation created: {path}
|
|
||||||
📁 Created directory: {path}
|
|
||||||
✅ {operation} completed successfully
|
|
||||||
❌ {operation} failed: {reason}
|
|
||||||
⚠ {operation} completed w/ warnings
|
|
||||||
|
|
||||||
## Best Practices
|
## Best Practices
|
||||||
|
|
||||||
**Task Creation:**
|
Task Creation:
|
||||||
- Define clear, specific objectives
|
- Clear requirements
|
||||||
- Break down complex work into manageable phases
|
- Measurable outcomes
|
||||||
- Set realistic timelines and expectations
|
- Realistic scope
|
||||||
- Include comprehensive context and requirements
|
- Defined boundaries
|
||||||
- Plan for testing and validation
|
- Success criteria
|
||||||
|
|
||||||
**Execution Management:**
|
Task Management:
|
||||||
- Update progress regularly and consistently
|
- Regular updates
|
||||||
- Document decisions and changes promptly
|
- Track blockers early
|
||||||
- Handle blockers and dependencies proactively
|
- Document decisions
|
||||||
- Maintain clean git history and commits
|
- Test incrementally
|
||||||
- Communicate status changes effectively
|
- Communicate progress
|
||||||
|
|
||||||
**Quality Assurance:**
|
## Examples
|
||||||
- Verify completion criteria before marking done
|
|
||||||
- Run comprehensive tests and validation
|
|
||||||
- Review code quality and standards compliance
|
|
||||||
- Update documentation and knowledge base
|
|
||||||
- Plan for maintenance and future enhancements
|
|
||||||
|
|
||||||
## Troubleshooting
|
```bash
|
||||||
- **Complex Tasks**: Use automatic breakdown with phase management
|
# Create complex feature task
|
||||||
- **Session Interruptions**: Leverage auto-save and context preservation
|
/task:create "Implement OAuth 2.0 authentication system"
|
||||||
- **Integration Issues**: Apply git checkpoints and rollback capabilities
|
|
||||||
- **Progress Tracking**: Use detailed phase and milestone tracking
|
|
||||||
|
|
||||||
## Success Messages
|
# Check task status
|
||||||
✅ {operation} completed successfully
|
/task:status oauth-task-id
|
||||||
📝 Created: {file_path}
|
|
||||||
✏ Updated: {file_path}
|
# Resume work after break
|
||||||
✨ Task completed: {task_title}
|
/task:resume oauth-task-id
|
||||||
|
|
||||||
|
# Update with discoveries
|
||||||
|
/task:update oauth-task-id "Found library conflict, switching approach"
|
||||||
|
|
||||||
|
# Complete with summary
|
||||||
|
/task:complete oauth-task-id
|
||||||
|
```
|
||||||
|
|
||||||
|
## Integration
|
||||||
|
|
||||||
|
Works with:
|
||||||
|
- TodoWrite for subtasks
|
||||||
|
- Git for version control
|
||||||
|
- Test for validation
|
||||||
|
- Document for artifacts
|
||||||
|
- All development commands
|
||||||
|
|
||||||
|
## Deliverables
|
||||||
|
|
||||||
|
- Task breakdown document
|
||||||
|
- Progress tracking reports
|
||||||
|
- Technical decisions log
|
||||||
|
- Implementation artifacts
|
||||||
|
- Completion summary
|
||||||
|
- Lessons learned
|
||||||
@@ -1,38 +1,6 @@
|
|||||||
# /test - Create and run comprehensive tests
|
# /test - Create and run comprehensive tests
|
||||||
|
|
||||||
## Legend
|
@include shared/universal-constants.yml#Universal_Legend
|
||||||
| Symbol | Meaning | | Abbrev | Meaning |
|
|
||||||
|--------|---------|---|--------|---------|
|
|
||||||
| → | leads to | | cfg | configuration |
|
|
||||||
| & | and/with | | impl | implementation |
|
|
||||||
| w/ | with | | perf | performance |
|
|
||||||
| @ | at/located | | ops | operations |
|
|
||||||
| > | greater than | | val | validation |
|
|
||||||
| ∀ | for all/every | | req | requirements |
|
|
||||||
| ∃ | exists/there is | | deps | dependencies |
|
|
||||||
| ∴ | therefore | | env | environment |
|
|
||||||
| ∵ | because | | db | database |
|
|
||||||
| ≡ | equivalent | | api | interface |
|
|
||||||
| ≈ | approximately | | docs | documentation |
|
|
||||||
| 📁 | directory/path | | std | standard |
|
|
||||||
| 🔢 | number/count | | def | default |
|
|
||||||
| 📝 | text/string | | ctx | context |
|
|
||||||
| ⚙ | setting/config | | err | error |
|
|
||||||
| 🎛 | control/flags | | exec | execution |
|
|
||||||
| 🔧 | configuration | | qual | quality |
|
|
||||||
| 📋 | group/category | | rec | recovery |
|
|
||||||
| 🚨 | critical/urgent | | sev | severity |
|
|
||||||
| ⚠ | warning/caution | | resp | response |
|
|
||||||
| 🔄 | retry/recovery | | esc | escalation |
|
|
||||||
| ✅ | success/fixed | | tok | token |
|
|
||||||
| ❌ | failure/error | | opt | optimization |
|
|
||||||
| ℹ | information | | UX | user experience |
|
|
||||||
| ⚡ | fast/quick | | UI | user interface |
|
|
||||||
| 🐌 | slow/delayed | | C | critical |
|
|
||||||
| ✨ | complete/done | | H | high |
|
|
||||||
| 📖 | read operation | | M | medium |
|
|
||||||
| ✏ | edit operation | | L | low |
|
|
||||||
| 🗑 | delete operation | | |
|
|
||||||
|
|
||||||
## Purpose
|
## Purpose
|
||||||
Create or run comprehensive test suites for code specified in $ARGUMENTS using modern testing frameworks and methodologies.
|
Create or run comprehensive test suites for code specified in $ARGUMENTS using modern testing frameworks and methodologies.
|
||||||
@@ -40,287 +8,72 @@ Create or run comprehensive test suites for code specified in $ARGUMENTS using m
|
|||||||
## Syntax
|
## Syntax
|
||||||
`/test [flags] [target]`
|
`/test [flags] [target]`
|
||||||
|
|
||||||
## Universal Flags
|
@include shared/flag-inheritance.yml#Universal_Always
|
||||||
--plan: "Show execution plan before running"
|
|
||||||
--uc: "UltraCompressed mode (~70% token reduction)"
|
Examples:
|
||||||
--ultracompressed: "Alias for --uc"
|
- `/test --tdd` - Test-driven development workflow
|
||||||
--think: "Multi-file analysis w/ context (4K tokens)"
|
- `/test --coverage` - Generate coverage report
|
||||||
--think-hard: "Deep architectural analysis (10K tokens)"
|
- `/test --watch` - Continuous test mode
|
||||||
--ultrathink: "Critical system redesign (32K tokens)"
|
- `/test --integration` - Run integration tests
|
||||||
--c7: "Enable Context7→library documentation lookup"
|
- `/test --e2e` - Run end-to-end tests
|
||||||
--seq: "Enable Sequential→complex analysis & thinking"
|
|
||||||
--magic: "Enable Magic→UI component generation"
|
|
||||||
--pup: "Enable Puppeteer→browser automation & testing"
|
|
||||||
--all-mcp: "Enable all MCP servers"
|
|
||||||
--no-mcp: "Disable all MCP servers (native tools only)"
|
|
||||||
--no-c7: "Disable Context7 specifically"
|
|
||||||
--no-seq: "Disable Sequential thinking specifically"
|
|
||||||
--no-magic: "Disable Magic UI builder specifically"
|
|
||||||
--no-pup: "Disable Puppeteer specifically"
|
|
||||||
|
|
||||||
## Command-Specific Flags
|
## Command-Specific Flags
|
||||||
|
--tdd: "Test-driven development workflow (write failing test→implement→pass)"
|
||||||
|
--coverage: "Generate detailed coverage reports w/ uncovered lines"
|
||||||
|
--integration: "Run integration tests across components/services"
|
||||||
|
--e2e: "Run end-to-end tests w/ real browser/environment"
|
||||||
|
--unit: "Focus on unit tests only (default)"
|
||||||
|
--mutation: "Run mutation testing to verify test quality"
|
||||||
|
--snapshot: "Update/verify snapshot tests"
|
||||||
|
--watch: "Run tests continuously on file changes"
|
||||||
|
--bail: "Stop on first test failure"
|
||||||
|
--parallel: "Run tests in parallel workers"
|
||||||
|
--update-snapshots: "Update all snapshot tests"
|
||||||
|
|
||||||
**Test Types:**
|
## Testing Approaches
|
||||||
- `--unit`: Unit tests for individual functions and components
|
|
||||||
- `--integration`: Integration tests for APIs, services, and database interactions
|
|
||||||
- `--e2e`: End-to-end tests for complete user workflows
|
|
||||||
- `--performance`: Performance and load testing
|
|
||||||
- `--security`: Security testing and vulnerability assessment
|
|
||||||
|
|
||||||
**Test Execution:**
|
**Unit Testing:** Isolated component/function tests | Mock all dependencies | Fast execution | High coverage target
|
||||||
- `--coverage`: Generate comprehensive code coverage reports
|
|
||||||
- `--watch`: Continuous test execution on file changes
|
|
||||||
- `--interactive`: Interactive test runner with real-time feedback
|
|
||||||
- `--parallel`: Run tests in parallel for faster execution
|
|
||||||
- `--isolated`: Run tests in isolated environments
|
|
||||||
|
|
||||||
**Testing Tools:**
|
**Integration Testing:** Component interaction tests | Real service calls | Database transactions | API endpoint tests
|
||||||
- `--pup`: Browser-based E2E testing with Puppeteer automation
|
|
||||||
- `--c7`: Testing framework documentation and best practices
|
|
||||||
- `--seq`: Complex test scenario planning and analysis
|
|
||||||
|
|
||||||
**Quality Control:**
|
**E2E Testing:** Full user workflows | Browser automation | Real environment | Critical path coverage
|
||||||
- `--strict`: Strict testing mode with enhanced validation
|
|
||||||
- `--threshold [percent]`: Set minimum coverage threshold (default 80%)
|
|
||||||
- `--fail-fast`: Stop on first test failure
|
|
||||||
- `--retry [count]`: Retry failed tests specified number of times
|
|
||||||
|
|
||||||
## Examples
|
**TDD Workflow:** Red→Green→Refactor cycle | Write minimal code | Comprehensive coverage | Design emergence
|
||||||
- `/test --unit --coverage --watch` → Unit tests with coverage and live updates
|
|
||||||
- `/test --e2e --pup --think` → E2E tests with Puppeteer and analysis
|
|
||||||
- `/test --integration --c7 --parallel` → Integration tests with docs and parallel execution
|
|
||||||
- `/test --performance --threshold 90 --seq` → Performance testing with high coverage threshold
|
|
||||||
- `/test --security --strict --interactive` → Security testing with strict validation
|
|
||||||
|
|
||||||
## Test Types and Implementation
|
## Testing Patterns
|
||||||
|
|
||||||
**Unit Tests:**
|
**Test Structure:** Arrange-Act-Assert (AAA) | Given-When-Then (BDD) | Setup→Execute→Verify→Teardown
|
||||||
- Test individual functions, methods, and components in isolation
|
|
||||||
- Mock external dependencies and services
|
|
||||||
- Focus on business logic and edge cases
|
|
||||||
- Ensure fast execution and high reliability
|
|
||||||
- Cover both happy paths and error conditions
|
|
||||||
|
|
||||||
**Integration Tests:**
|
**Coverage Targets:** Statements: 80%+ | Branches: 75%+ | Functions: 90%+ | Lines: 80%+
|
||||||
- Test interactions between components and services
|
|
||||||
- Verify API contracts and data flow
|
|
||||||
- Test database operations and transactions
|
|
||||||
- Validate external service integrations
|
|
||||||
- Check error handling and recovery mechanisms
|
|
||||||
|
|
||||||
**End-to-End Tests:**
|
**Test Organization:**
|
||||||
- Test complete user workflows and journeys
|
- `__tests__/` or `test/` directories
|
||||||
- Verify critical business paths through application
|
- `*.test.{js,ts}` or `*.spec.{js,ts}` naming
|
||||||
- Include both success and failure scenarios
|
- Mirror source structure in test directories
|
||||||
- Test across different browsers and devices
|
- Group by feature or component
|
||||||
- Validate user interface interactions and responses
|
|
||||||
|
|
||||||
**Performance Tests:**
|
@include shared/quality-patterns.yml#Test_Quality_Standards
|
||||||
- Load testing with realistic user scenarios
|
|
||||||
- Stress testing to identify breaking points
|
|
||||||
- Spike testing for traffic surge handling
|
|
||||||
- Volume testing with large datasets
|
|
||||||
- Endurance testing for long-running operations
|
|
||||||
|
|
||||||
**Security Tests:**
|
## Framework Support
|
||||||
- Vulnerability scanning and penetration testing
|
|
||||||
- Authentication and authorization testing
|
|
||||||
- Input validation and injection attack prevention
|
|
||||||
- Data encryption and privacy protection
|
|
||||||
- Session management and access control verification
|
|
||||||
|
|
||||||
## Pre-Test Setup and Cleanup
|
**JavaScript/TypeScript:** Jest (default) | Mocha + Chai | Vitest | Testing Library
|
||||||
|
|
||||||
**Environment Preparation:**
|
**Python:** pytest (default) | unittest | nose2 | doctest
|
||||||
- Clean test output directories (coverage/, test-results/)
|
|
||||||
- Remove artifacts from previous test runs
|
|
||||||
- Reset test databases to clean baseline state
|
|
||||||
- Clear test cache and temporary files
|
|
||||||
- Initialize test data and fixtures
|
|
||||||
|
|
||||||
**Dependency Management:**
|
**Go:** Built-in testing | Testify | Ginkgo/Gomega
|
||||||
- Install and update testing dependencies
|
|
||||||
- Configure test environments and settings
|
|
||||||
- Set up mock services and test doubles
|
|
||||||
- Prepare test databases and seed data
|
|
||||||
- Configure network and security settings
|
|
||||||
|
|
||||||
## Coverage Analysis (--coverage)
|
**Java:** JUnit 5 | TestNG | Mockito | Spring Test
|
||||||
|
|
||||||
**Coverage Metrics:**
|
**Other:** Framework-specific best practices | Native test runners
|
||||||
- Line coverage: Percentage of executed code lines
|
|
||||||
- Branch coverage: Percentage of executed conditional branches
|
|
||||||
- Function coverage: Percentage of called functions
|
|
||||||
- Statement coverage: Percentage of executed statements
|
|
||||||
- Path coverage: Percentage of executed code paths
|
|
||||||
|
|
||||||
**Coverage Goals:**
|
|
||||||
- Aim for >80% overall code coverage
|
|
||||||
- Focus on critical business logic coverage
|
|
||||||
- Identify untested code paths and edge cases
|
|
||||||
- Track coverage trends and improvements
|
|
||||||
- Generate actionable coverage reports
|
|
||||||
|
|
||||||
**Coverage Reports:**
|
|
||||||
- HTML reports with detailed line-by-line analysis
|
|
||||||
- JSON reports for programmatic consumption
|
|
||||||
- XML reports for CI/CD integration
|
|
||||||
- Summary reports with key metrics
|
|
||||||
- Trend analysis and historical comparison
|
|
||||||
|
|
||||||
## Watch Mode (--watch)
|
|
||||||
|
|
||||||
**Continuous Testing:**
|
|
||||||
- Automatic test execution on file changes
|
|
||||||
- Smart test selection based on changed files
|
|
||||||
- Fast feedback loop during development
|
|
||||||
- Real-time coverage updates
|
|
||||||
- Efficient resource utilization
|
|
||||||
|
|
||||||
**Change Detection:**
|
|
||||||
- Monitor source code files for modifications
|
|
||||||
- Track test file changes and updates
|
|
||||||
- Detect configuration and dependency changes
|
|
||||||
- Handle file system events efficiently
|
|
||||||
- Provide clear change notifications
|
|
||||||
|
|
||||||
## Interactive Mode (--interactive)
|
|
||||||
|
|
||||||
**Interactive Features:**
|
|
||||||
- Test selection and filtering capabilities
|
|
||||||
- Real-time test execution and results
|
|
||||||
- Step-through debugging for failing tests
|
|
||||||
- Live code coverage visualization
|
|
||||||
- Dynamic test configuration and options
|
|
||||||
|
|
||||||
**User Experience:**
|
|
||||||
- Clear and intuitive command interface
|
|
||||||
- Rich output formatting and highlighting
|
|
||||||
- Progress indicators and status updates
|
|
||||||
- Error highlighting and debugging aids
|
|
||||||
- Keyboard shortcuts and navigation
|
|
||||||
|
|
||||||
## Testing Best Practices
|
|
||||||
|
|
||||||
**Test Structure and Organization:**
|
|
||||||
- Use descriptive test names explaining what is being tested
|
|
||||||
- Follow AAA pattern: Arrange, Act, Assert
|
|
||||||
- Group related tests in logical test suites
|
|
||||||
- Maintain consistent test file organization
|
|
||||||
- Use clear and readable test code
|
|
||||||
|
|
||||||
**Test Independence:**
|
|
||||||
- Ensure tests can run in any order
|
|
||||||
- Avoid dependencies between tests
|
|
||||||
- Clean up test state after each test
|
|
||||||
- Use fresh test data for each test
|
|
||||||
- Mock external dependencies appropriately
|
|
||||||
|
|
||||||
**Test Data Management:**
|
|
||||||
- Create reusable test fixtures and factories
|
|
||||||
- Use meaningful test data that reflects real scenarios
|
|
||||||
- Maintain test data separately from production data
|
|
||||||
- Implement data seeding and cleanup procedures
|
|
||||||
- Version control test data and schemas
|
|
||||||
|
|
||||||
**Mocking and Test Doubles:**
|
|
||||||
- Mock external services and APIs
|
|
||||||
- Use test doubles for database interactions
|
|
||||||
- Stub complex dependencies and integrations
|
|
||||||
- Verify mock interactions and expectations
|
|
||||||
- Balance mocking with integration testing
|
|
||||||
|
|
||||||
## Test Framework Integration
|
|
||||||
|
|
||||||
**Supported Frameworks:**
|
|
||||||
- **Jest**: Modern JavaScript testing framework
|
|
||||||
- **Mocha/Chai**: Flexible Node.js testing suite
|
|
||||||
- **Pytest**: Python testing framework
|
|
||||||
- **JUnit**: Java testing framework
|
|
||||||
- **RSpec**: Ruby testing framework
|
|
||||||
|
|
||||||
**CI/CD Integration:**
|
|
||||||
- Automated test execution in pipelines
|
|
||||||
- Test result reporting and notifications
|
|
||||||
- Coverage threshold enforcement
|
|
||||||
- Parallel test execution for speed
|
|
||||||
- Test artifact collection and storage
|
|
||||||
|
|
||||||
## Deliverables
|
## Deliverables
|
||||||
- **Test Suites**: Comprehensive test coverage for all specified areas
|
|
||||||
- **Coverage Reports**: Detailed code coverage analysis and metrics
|
|
||||||
- **Test Documentation**: Test plans, strategies, and maintenance guides
|
|
||||||
- **CI/CD Integration**: Automated testing pipeline configuration
|
|
||||||
- **Performance Baselines**: Performance test results and benchmarks
|
|
||||||
|
|
||||||
## Output Locations
|
**Test Files:** Created in appropriate test directories | Following naming conventions | Comprehensive test cases
|
||||||
- **Coverage Reports**: `coverage/` directory with HTML, JSON, and XML reports
|
|
||||||
- **Test Results**: `test-results/` directory with detailed test outcomes
|
|
||||||
- **Performance Reports**: `.claudedocs/metrics/performance-test-{timestamp}.md`
|
|
||||||
- **Test Documentation**: `.claudedocs/reports/test-strategy-{timestamp}.md`
|
|
||||||
|
|
||||||
## Research Requirements
|
**Coverage Reports:** HTML report in `coverage/` | Console summary | Uncovered line identification
|
||||||
External_Library_Research:
|
|
||||||
- Identify library/framework mentioned
|
|
||||||
- Context7 lookup for official documentation
|
|
||||||
- Verify API patterns and examples
|
|
||||||
- Check version compatibility
|
|
||||||
- Document findings in implementation
|
|
||||||
Pattern_Research:
|
|
||||||
- Search existing codebase for similar patterns
|
|
||||||
- Magic component search if UI-related
|
|
||||||
- WebSearch for official documentation
|
|
||||||
- Validate approach with Sequential thinking
|
|
||||||
- Document pattern choice rationale
|
|
||||||
API_Integration_Research:
|
|
||||||
- Official documentation lookup
|
|
||||||
- Authentication requirements
|
|
||||||
- Rate limiting and error handling
|
|
||||||
- SDK availability and examples
|
|
||||||
- Integration testing approach
|
|
||||||
|
|
||||||
## Report Notifications
|
**CI Configuration:** GitHub Actions | CircleCI | Jenkins | GitLab CI
|
||||||
📄 Analysis report saved to: {path}
|
|
||||||
📊 Metrics updated: {path}
|
|
||||||
📋 Summary saved to: {path}
|
|
||||||
💾 Checkpoint created: {path}
|
|
||||||
📚 Documentation created: {path}
|
|
||||||
📁 Created directory: {path}
|
|
||||||
✅ {operation} completed successfully
|
|
||||||
❌ {operation} failed: {reason}
|
|
||||||
⚠ {operation} completed w/ warnings
|
|
||||||
|
|
||||||
## Quality Assurance Standards
|
**Documentation:** Test plan | Test cases | Coverage goals | CI/CD integration
|
||||||
|
|
||||||
**Test Quality:**
|
@include shared/universal-constants.yml#Success_Messages
|
||||||
- Tests should be reliable and deterministic
|
|
||||||
- Avoid flaky tests that pass/fail inconsistently
|
|
||||||
- Maintain high test code quality standards
|
|
||||||
- Regular test review and refactoring
|
|
||||||
- Continuous improvement of test effectiveness
|
|
||||||
|
|
||||||
**Coverage Standards:**
|
|
||||||
- Minimum 80% code coverage for new code
|
|
||||||
- 100% coverage for critical business logic
|
|
||||||
- Track and improve coverage over time
|
|
||||||
- Focus on meaningful coverage, not just metrics
|
|
||||||
- Regular coverage analysis and reporting
|
|
||||||
|
|
||||||
**Performance Standards:**
|
|
||||||
- Unit tests should execute in milliseconds
|
|
||||||
- Integration tests should complete within seconds
|
|
||||||
- E2E tests should finish within reasonable timeframes
|
|
||||||
- Parallel execution for improved speed
|
|
||||||
- Regular performance optimization and monitoring
|
|
||||||
|
|
||||||
## Troubleshooting
|
|
||||||
- **Slow Tests**: Use `--parallel` and optimize test performance
|
|
||||||
- **Flaky E2E Tests**: Apply `--retry` and improve test stability
|
|
||||||
- **Low Coverage**: Use `--coverage --interactive` for targeted improvement
|
|
||||||
- **Complex Scenarios**: Combine `--seq --think-hard` for comprehensive planning
|
|
||||||
|
|
||||||
## Success Messages
|
|
||||||
✅ {operation} completed successfully
|
|
||||||
📝 Created: {file_path}
|
|
||||||
✏ Updated: {file_path}
|
|
||||||
✨ Task completed: {task_title}
|
|
||||||
@@ -1,328 +1,58 @@
|
|||||||
# /troubleshoot - Debug and resolve issues systematically
|
# /troubleshoot - Debug and resolve issues systematically
|
||||||
|
|
||||||
## Legend
|
@include shared/universal-constants.yml#Universal_Legend
|
||||||
| Symbol | Meaning | | Abbrev | Meaning |
|
|
||||||
|--------|---------|---|--------|---------|
|
|
||||||
| → | leads to | | cfg | configuration |
|
|
||||||
| & | and/with | | impl | implementation |
|
|
||||||
| w/ | with | | perf | performance |
|
|
||||||
| @ | at/located | | ops | operations |
|
|
||||||
| > | greater than | | val | validation |
|
|
||||||
| ∀ | for all/every | | req | requirements |
|
|
||||||
| ∃ | exists/there is | | deps | dependencies |
|
|
||||||
| ∴ | therefore | | env | environment |
|
|
||||||
| ∵ | because | | db | database |
|
|
||||||
| ≡ | equivalent | | api | interface |
|
|
||||||
| ≈ | approximately | | docs | documentation |
|
|
||||||
| 📁 | directory/path | | std | standard |
|
|
||||||
| 🔢 | number/count | | def | default |
|
|
||||||
| 📝 | text/string | | ctx | context |
|
|
||||||
| ⚙ | setting/config | | err | error |
|
|
||||||
| 🎛 | control/flags | | exec | execution |
|
|
||||||
| 🔧 | configuration | | qual | quality |
|
|
||||||
| 📋 | group/category | | rec | recovery |
|
|
||||||
| 🚨 | critical/urgent | | sev | severity |
|
|
||||||
| ⚠ | warning/caution | | resp | response |
|
|
||||||
| 🔄 | retry/recovery | | esc | escalation |
|
|
||||||
| ✅ | success/fixed | | tok | token |
|
|
||||||
| ❌ | failure/error | | opt | optimization |
|
|
||||||
| ℹ | information | | UX | user experience |
|
|
||||||
| ⚡ | fast/quick | | UI | user interface |
|
|
||||||
| 🐌 | slow/delayed | | C | critical |
|
|
||||||
| ✨ | complete/done | | H | high |
|
|
||||||
| 📖 | read operation | | M | medium |
|
|
||||||
| ✏ | edit operation | | L | low |
|
|
||||||
| 🗑 | delete operation | | |
|
|
||||||
|
|
||||||
## Purpose
|
## Purpose
|
||||||
Debug and resolve issues in code or systems specified in $ARGUMENTS using systematic troubleshooting methodologies and analysis techniques.
|
Systematically debug and resolve issues in $ARGUMENTS using root cause analysis and evidence-based solutions.
|
||||||
|
|
||||||
## Syntax
|
## Syntax
|
||||||
`/troubleshoot [flags] [issue-description]`
|
`/troubleshoot [flags] [issue-description]`
|
||||||
|
|
||||||
## Universal Flags
|
@include shared/flag-inheritance.yml#Universal_Always
|
||||||
--plan: "Show execution plan before running"
|
|
||||||
--uc: "UltraCompressed mode (~70% token reduction)"
|
Examples:
|
||||||
--ultracompressed: "Alias for --uc"
|
- `/troubleshoot "app crashes on startup"` - Debug crash
|
||||||
--think: "Multi-file analysis w/ context (4K tokens)"
|
- `/troubleshoot --performance "slow API"` - Performance issues
|
||||||
--think-hard: "Deep architectural analysis (10K tokens)"
|
- `/troubleshoot --interactive "login fails"` - Guided debugging
|
||||||
--ultrathink: "Critical system redesign (32K tokens)"
|
|
||||||
--c7: "Enable Context7→library documentation lookup"
|
|
||||||
--seq: "Enable Sequential→complex analysis & thinking"
|
|
||||||
--magic: "Enable Magic→UI component generation"
|
|
||||||
--pup: "Enable Puppeteer→browser automation & testing"
|
|
||||||
--all-mcp: "Enable all MCP servers"
|
|
||||||
--no-mcp: "Disable all MCP servers (native tools only)"
|
|
||||||
--no-c7: "Disable Context7 specifically"
|
|
||||||
--no-seq: "Disable Sequential thinking specifically"
|
|
||||||
--no-magic: "Disable Magic UI builder specifically"
|
|
||||||
--no-pup: "Disable Puppeteer specifically"
|
|
||||||
|
|
||||||
## Command-Specific Flags
|
## Command-Specific Flags
|
||||||
|
--performance: "Focus on performance bottlenecks"
|
||||||
|
--memory: "Memory leak detection and analysis"
|
||||||
|
--network: "Network-related debugging"
|
||||||
|
--interactive: "Step-by-step guided troubleshooting"
|
||||||
|
--trace: "Enable detailed execution tracing"
|
||||||
|
--bisect: "Git bisect to find breaking commit"
|
||||||
|
|
||||||
**Troubleshooting Modes:**
|
## Troubleshooting Approach
|
||||||
- `--investigate`: Focus on understanding and analyzing issues without immediate fixes
|
|
||||||
- `--fix`: Complete bug-fixing workflow with testing and verification (default)
|
|
||||||
- `--analyze`: Deep technical analysis of complex system interactions
|
|
||||||
- `--diagnose`: Systematic diagnostic approach with structured methodology
|
|
||||||
|
|
||||||
**Analysis Methods:**
|
**1. Reproduce:** Isolate minimal reproduction | Document steps | Verify consistency | Capture full context
|
||||||
- `--five-whys`: Apply root cause analysis methodology iteratively
|
|
||||||
- `--binary-search`: Use binary search approach to isolate problem scope
|
|
||||||
- `--timeline`: Analyze issue timeline and recent changes
|
|
||||||
- `--dependencies`: Focus on dependency and integration issues
|
|
||||||
|
|
||||||
**Environment Focus:**
|
**2. Gather Evidence:** Error messages & stack traces | Logs & metrics | System state | Recent changes | Environment differences
|
||||||
- `--prod`: Production-specific issue handling with minimal disruption
|
|
||||||
- `--staging`: Staging environment debugging and testing
|
|
||||||
- `--local`: Local development environment troubleshooting
|
|
||||||
- `--cross-env`: Cross-environment consistency analysis
|
|
||||||
|
|
||||||
**Investigation Tools:**
|
**3. Form Hypotheses:** Most likely causes | Alternative explanations | Test predictions | Rule out possibilities
|
||||||
- `--logs`: Focus on log analysis and pattern detection
|
|
||||||
- `--performance`: Performance profiling and bottleneck analysis
|
|
||||||
- `--security`: Security-focused investigation and vulnerability analysis
|
|
||||||
- `--network`: Network connectivity and API integration debugging
|
|
||||||
|
|
||||||
## Examples
|
**4. Test & Verify:** Targeted experiments | Change one variable | Document results | Confirm root cause
|
||||||
- `/troubleshoot --investigate --logs --think` → Log analysis with context
|
|
||||||
- `/troubleshoot --five-whys --prod --think-hard` → Production root cause analysis
|
|
||||||
- `/troubleshoot --fix --performance --ultrathink` → Performance issue resolution
|
|
||||||
- `/troubleshoot --binary-search --dependencies` → Systematic dependency debugging
|
|
||||||
- `/troubleshoot --analyze --security --network` → Security and network analysis
|
|
||||||
|
|
||||||
## Troubleshooting Workflow
|
**5. Fix & Prevent:** Implement solution | Add tests | Document fix | Prevent recurrence
|
||||||
|
|
||||||
**1. Issue Reproduction and Understanding**
|
## Common Issue Categories
|
||||||
- **Minimal Reproduction**: Create smallest possible reproduction case
|
|
||||||
- **Behavior Documentation**: Document expected vs actual behavior clearly
|
|
||||||
- **Impact Assessment**: Identify affected components, users, and business impact
|
|
||||||
- **Severity Classification**: Determine urgency and priority level
|
|
||||||
- **Environment Analysis**: Understand where and when the issue occurs
|
|
||||||
|
|
||||||
**2. Investigation and Isolation**
|
**Performance:** Slow queries | Memory leaks | CPU bottlenecks | Network latency | Inefficient algorithms
|
||||||
- **Tool Utilization**: Apply debugging tools and strategic logging
|
|
||||||
- **Scope Narrowing**: Use binary search to isolate problem area
|
|
||||||
- **Change Analysis**: Review recent changes using git history and blame
|
|
||||||
- **Data Collection**: Analyze logs, stack traces, and monitoring data
|
|
||||||
- **Factor Elimination**: Rule out environmental and configuration factors
|
|
||||||
|
|
||||||
**3. Root Cause Analysis**
|
**Crashes/Errors:** Null references | Type mismatches | Race conditions | Memory corruption | Stack overflow
|
||||||
- **Underlying Causes**: Look beyond symptoms to find root causes
|
|
||||||
- **Five-Whys Method**: Apply iterative questioning technique
|
|
||||||
- **Systemic Analysis**: Consider broader system and process issues
|
|
||||||
- **Contributing Factors**: Document all factors that led to the issue
|
|
||||||
- **Pattern Recognition**: Identify similar issues and common causes
|
|
||||||
|
|
||||||
**4. Solution Development (--fix mode)**
|
**Integration:** API failures | Authentication issues | Version conflicts | Configuration problems | Network timeouts
|
||||||
- **Test Creation**: Write failing test that reproduces the issue
|
|
||||||
- **Minimal Fix**: Implement focused solution addressing root cause
|
|
||||||
- **Compatibility**: Ensure backward compatibility and minimal disruption
|
|
||||||
- **Edge Cases**: Consider side effects and edge case scenarios
|
|
||||||
- **Code Review**: Apply standard code review and quality practices
|
|
||||||
|
|
||||||
**5. Verification and Prevention**
|
**Data Issues:** Corruption | Inconsistency | Migration failures | Encoding problems | Concurrency conflicts
|
||||||
- **Fix Validation**: Verify solution resolves issue completely
|
|
||||||
- **Regression Testing**: Run full test suite to prevent regressions
|
|
||||||
- **Realistic Testing**: Test in production-like conditions
|
|
||||||
- **Monitoring**: Add monitoring and alerting for early detection
|
|
||||||
- **Documentation**: Record lessons learned and prevention measures
|
|
||||||
|
|
||||||
## Investigation Techniques
|
@include shared/quality-patterns.yml#Root_Cause_Analysis
|
||||||
|
|
||||||
**Debugging Approaches:**
|
|
||||||
- **Strategic Logging**: Add targeted logging at key decision points
|
|
||||||
- **Breakpoint Analysis**: Use debugger breakpoints for step-through analysis
|
|
||||||
- **State Inspection**: Examine variable states and data structures
|
|
||||||
- **Call Stack Analysis**: Trace execution paths and function calls
|
|
||||||
- **Memory Debugging**: Analyze memory usage and potential leaks
|
|
||||||
|
|
||||||
**Performance Analysis:**
|
|
||||||
- **Profiling Tools**: Use performance profilers for bottleneck identification
|
|
||||||
- **Resource Monitoring**: Track CPU, memory, and I/O usage patterns
|
|
||||||
- **Query Analysis**: Analyze database queries and execution plans
|
|
||||||
- **Network Inspection**: Monitor network requests and response times
|
|
||||||
- **Caching Evaluation**: Assess caching effectiveness and hit rates
|
|
||||||
|
|
||||||
**System Analysis:**
|
|
||||||
- **Configuration Review**: Examine system and application configurations
|
|
||||||
- **Dependency Mapping**: Map and analyze component dependencies
|
|
||||||
- **Integration Testing**: Test inter-service communication and APIs
|
|
||||||
- **Infrastructure Analysis**: Review infrastructure and deployment setup
|
|
||||||
- **Security Assessment**: Analyze security configurations and access controls
|
|
||||||
|
|
||||||
## Five-Whys Analysis (--five-whys)
|
|
||||||
|
|
||||||
**Methodology:**
|
|
||||||
1. **Problem Statement**: Clearly define the observed problem
|
|
||||||
2. **First Why**: Why did this problem occur? (immediate cause)
|
|
||||||
3. **Second Why**: Why did that cause occur? (deeper cause)
|
|
||||||
4. **Third Why**: Why did that deeper cause occur? (root cause)
|
|
||||||
5. **Fourth Why**: Why does that root cause exist? (systemic cause)
|
|
||||||
6. **Fifth Why**: Why is that system in place? (organizational cause)
|
|
||||||
|
|
||||||
**Documentation:**
|
|
||||||
- Record each level of analysis with evidence
|
|
||||||
- Document contributing factors at each level
|
|
||||||
- Identify prevention measures for each cause
|
|
||||||
- Propose systemic improvements to prevent recurrence
|
|
||||||
- Create action items for short-term and long-term fixes
|
|
||||||
|
|
||||||
## Production Issue Handling (--prod)
|
|
||||||
|
|
||||||
**Production-Specific Considerations:**
|
|
||||||
- **Minimal Disruption**: Prioritize system stability and user experience
|
|
||||||
- **Rollback Readiness**: Prepare immediate rollback options
|
|
||||||
- **Monitoring Integration**: Use existing monitoring and alerting systems
|
|
||||||
- **Communication**: Maintain stakeholder communication throughout
|
|
||||||
- **Documentation**: Record all changes and decisions for audit trail
|
|
||||||
|
|
||||||
**Production Analysis:**
|
|
||||||
- **Deployment Correlation**: Correlate issues with recent deployments
|
|
||||||
- **Traffic Patterns**: Analyze user traffic and usage patterns
|
|
||||||
- **Configuration Changes**: Review recent configuration modifications
|
|
||||||
- **Resource Utilization**: Monitor system resource usage and limits
|
|
||||||
- **Service Dependencies**: Check health of dependent services
|
|
||||||
|
|
||||||
**Safe Production Practices:**
|
|
||||||
- **Feature Flags**: Use feature toggles to isolate problematic features
|
|
||||||
- **Gradual Rollout**: Implement fixes gradually with monitoring
|
|
||||||
- **A/B Testing**: Compare fix effectiveness with control groups
|
|
||||||
- **Circuit Breakers**: Implement circuit breakers for failing services
|
|
||||||
- **Health Checks**: Continuous health monitoring during fixes
|
|
||||||
|
|
||||||
## Investigation Tools and Techniques
|
|
||||||
|
|
||||||
**Logging and Monitoring:**
|
|
||||||
- Centralized log aggregation and analysis
|
|
||||||
- Real-time monitoring dashboards and alerts
|
|
||||||
- Distributed tracing for microservices
|
|
||||||
- Application performance monitoring (APM)
|
|
||||||
- Custom metrics and business intelligence
|
|
||||||
|
|
||||||
**Debugging Tools:**
|
|
||||||
- Interactive debuggers and IDE integration
|
|
||||||
- Remote debugging capabilities
|
|
||||||
- Memory profilers and leak detectors
|
|
||||||
- Performance profiling tools
|
|
||||||
- Network traffic analyzers
|
|
||||||
|
|
||||||
**Testing and Validation:**
|
|
||||||
- Unit test creation for bug reproduction
|
|
||||||
- Integration testing for component interactions
|
|
||||||
- Load testing for performance issues
|
|
||||||
- Security testing for vulnerability assessment
|
|
||||||
- Chaos engineering for resilience testing
|
|
||||||
|
|
||||||
## Deliverables
|
## Deliverables
|
||||||
- **Investigation Report**: Comprehensive analysis of issue and findings
|
|
||||||
- **Root Cause Analysis**: Detailed five-whys analysis with evidence
|
|
||||||
- **Solution Documentation**: Fix implementation with rationale
|
|
||||||
- **Prevention Plan**: Measures to prevent similar issues
|
|
||||||
- **Monitoring Enhancements**: Improved detection and alerting
|
|
||||||
- **Lessons Learned**: Knowledge base updates and team learnings
|
|
||||||
|
|
||||||
## Output Locations
|
**Root Cause Report:** Issue description | Evidence collected | Analysis process | Root cause identified | Fix implemented
|
||||||
- **Incident Reports**: `.claudedocs/incidents/rca-{issue}-{timestamp}.md`
|
|
||||||
- **Investigation Logs**: `.claudedocs/reports/troubleshoot-{timestamp}.md`
|
|
||||||
- **Solution Documentation**: `.claudedocs/summaries/fix-{issue}-{timestamp}.md`
|
|
||||||
|
|
||||||
## Research Requirements
|
**Fix Documentation:** What was broken | Why it broke | How it was fixed | Prevention measures | Test cases added
|
||||||
External_Library_Research:
|
|
||||||
- Identify library/framework mentioned
|
|
||||||
- Context7 lookup for official documentation
|
|
||||||
- Verify API patterns and examples
|
|
||||||
- Check version compatibility
|
|
||||||
- Document findings in implementation
|
|
||||||
Pattern_Research:
|
|
||||||
- Search existing codebase for similar patterns
|
|
||||||
- Magic component search if UI-related
|
|
||||||
- WebSearch for official documentation
|
|
||||||
- Validate approach with Sequential thinking
|
|
||||||
- Document pattern choice rationale
|
|
||||||
API_Integration_Research:
|
|
||||||
- Official documentation lookup
|
|
||||||
- Authentication requirements
|
|
||||||
- Rate limiting and error handling
|
|
||||||
- SDK availability and examples
|
|
||||||
- Integration testing approach
|
|
||||||
|
|
||||||
## Report Notifications
|
**Knowledge Base:** Problem→Solution mapping | Troubleshooting guides | Common patterns | Prevention checklist
|
||||||
📄 Analysis report saved to: {path}
|
|
||||||
📊 Metrics updated: {path}
|
|
||||||
📋 Summary saved to: {path}
|
|
||||||
💾 Checkpoint created: {path}
|
|
||||||
📚 Documentation created: {path}
|
|
||||||
📁 Created directory: {path}
|
|
||||||
✅ {operation} completed successfully
|
|
||||||
❌ {operation} failed: {reason}
|
|
||||||
⚠ {operation} completed w/ warnings
|
|
||||||
|
|
||||||
## Best Practices
|
@include shared/universal-constants.yml#Success_Messages
|
||||||
|
|
||||||
**Systematic Approach:**
|
|
||||||
- Follow structured troubleshooting methodology
|
|
||||||
- Document findings and decisions throughout process
|
|
||||||
- Maintain objectivity and avoid assumption-based debugging
|
|
||||||
- Use data and evidence to drive investigation
|
|
||||||
- Consider multiple hypotheses before settling on solutions
|
|
||||||
|
|
||||||
**Collaboration and Communication:**
|
|
||||||
- Involve relevant team members and stakeholders
|
|
||||||
- Communicate status and findings regularly
|
|
||||||
- Share knowledge and learnings with team
|
|
||||||
- Document solutions for future reference
|
|
||||||
- Conduct post-incident reviews for improvement
|
|
||||||
|
|
||||||
**Prevention Focus:**
|
|
||||||
- Address root causes, not just symptoms
|
|
||||||
- Implement monitoring and alerting improvements
|
|
||||||
- Update processes and procedures based on learnings
|
|
||||||
- Enhance testing and quality assurance practices
|
|
||||||
- Build resilience and error handling into systems
|
|
||||||
|
|
||||||
## Common Error Scenarios
|
|
||||||
|
|
||||||
### Database Connection Issues
|
|
||||||
```bash
|
|
||||||
/troubleshoot --investigate --dependencies "connection timeout"
|
|
||||||
# → Checks DB connectivity, credentials, network latency
|
|
||||||
# → Verifies connection pool settings and timeouts
|
|
||||||
# → Tests failover mechanisms and retry logic
|
|
||||||
```
|
|
||||||
|
|
||||||
### Memory Leaks & Performance
|
|
||||||
```bash
|
|
||||||
/troubleshoot --performance --logs --binary-search
|
|
||||||
# → Profiles memory usage patterns over time
|
|
||||||
# → Identifies allocation hotspots and retention issues
|
|
||||||
# → Implements heap dump analysis and GC tuning
|
|
||||||
```
|
|
||||||
|
|
||||||
### Production Emergencies
|
|
||||||
```bash
|
|
||||||
/troubleshoot --prod --investigate --timeline --critical
|
|
||||||
# → Creates incident timeline with system events
|
|
||||||
# → Preserves logs and state for post-mortem analysis
|
|
||||||
# → Implements safe rollback procedures if needed
|
|
||||||
```
|
|
||||||
|
|
||||||
### Integration & API Failures
|
|
||||||
```bash
|
|
||||||
/troubleshoot --dependencies --network --cross-env
|
|
||||||
# → Tests API endpoints and service dependencies
|
|
||||||
# → Validates authentication and authorization flows
|
|
||||||
# → Checks rate limiting and circuit breaker status
|
|
||||||
```
|
|
||||||
|
|
||||||
## Troubleshooting
|
|
||||||
- **Complex Issues**: Use `--ultrathink --five-whys` for comprehensive analysis
|
|
||||||
- **Production Emergencies**: Apply `--prod --investigate --timeline` for safe handling
|
|
||||||
- **Performance Problems**: Combine `--performance --logs --binary-search`
|
|
||||||
- **Integration Issues**: Use `--dependencies --network --cross-env`
|
|
||||||
|
|
||||||
## Success Messages
|
|
||||||
✅ {operation} completed successfully
|
|
||||||
📝 Created: {file_path}
|
|
||||||
✏ Updated: {file_path}
|
|
||||||
✨ Task completed: {task_title}
|
|
||||||
Reference in New Issue
Block a user