@northbridge-security/secureai 0.1.13

package/.claude/commands/architect/kiss.md

@@ -0,0 +1,762 @@
+---
+description: Analyze code for over-engineering and propose simplifications using KISS principles
+argument-hint: [scope] [--strict] [--apply] [--compare]
+allowed-tools: Task, Read, Write, Bash
+---
+
+# KISS Analysis: $ARGUMENTS
+
+**Note**: KISS (Keep It Simple, Stupid) principles and Clean Architecture complement each other. KISS focuses on removing unnecessary complexity and over-engineering, while Clean Architecture ensures proper separation of concerns and testability. Use `/architect:clean` to analyze architecture violations, then `/architect:kiss` to simplify the resulting code. See [Clean Architecture Analysis](./clean.md) for architectural refactoring.
+
+## Phase 0: Parse Arguments
+
+Extract from `$ARGUMENTS`:
+
+- **Scope**: Optional with smart defaults
+  - File path (e.g., `src/utils/auth.ts`) → Analyze specific file
+  - Directory path (e.g., `src/`) → Analyze all files in directory
+  - Pattern (e.g., `src/**/*.ts`) → Analyze matching files
+  - `--diff` or empty → Analyze git-changed files only
+- **--strict**: Fail if complexity thresholds are exceeded
+- **--apply**: Apply suggested changes to worktree (requires review)
+- **--compare**: Compare with previous `.kiss.local.md` report
+
+**Smart scope resolution:**
+
+```bash
+# If no scope provided or --diff flag
+if [[ -z "$SCOPE" ]] || [[ "$SCOPE" == "--diff" ]]; then
+  MODE="diff"
+  SCOPE=$(git diff --name-only origin/main...HEAD 2>/dev/null | grep -E '\.(ts|js|tsx|jsx)$')
+  echo "🔍 Analyzing git-changed files only"
+fi
+
+# If scope is a single file
+if [[ -f "$SCOPE" ]]; then
+  MODE="file"
+  echo "📄 Analyzing single file: $SCOPE"
+fi
+
+# If scope is a directory
+if [[ -d "$SCOPE" ]]; then
+  MODE="directory"
+  echo "📁 Analyzing directory: $SCOPE"
+fi
+
+# If scope is a pattern
+if [[ "$SCOPE" == *"*"* ]]; then
+  MODE="pattern"
+  echo "🔎 Analyzing pattern: $SCOPE"
+fi
+```
+
+## Phase 1: Launch KISS Simplifier Agent
+
+Invoke the specialized KISS Simplifier agent (see `docs/agents/kiss-simplifier.md`) to perform analysis.
+
+**Agent invocation:**
+
+```typescript
+// Launch agent via Task tool
+await Task({
+  subagent_type: "kiss-simplifier",
+  description: "Analyze code for over-engineering",
+  prompt: `Analyze the following scope for over-engineering and complexity issues:
+
+Scope: ${scope}
+Mode: ${mode}
+Strict mode: ${strictMode}
+Apply changes: ${applyChanges}
+
+Use KISS principles from detecting-overengineered-code.local.md to identify:
+1. Dead code and unused exports
+2. Unnecessary complexity and abstraction
+3. Architecture violations
+4. AI-generated patterns (verbose naming, generic comments)
+5. Outdated patterns (var usage, callback hell, God objects)
+
+Create a git worktree for proposed changes at: .worktree/kiss-${timestamp}
+
+Report findings with:
+- Issue severity (critical, high, medium, low)
+- Specific code locations
+- Proposed simplifications
+- Worktree diff summary
+
+Return findings in structured format for review.`,
+});
+```
+
+**What the agent will do:**
+
+1. Read and understand KISS principles from `detecting-overengineered-code.local.md`
+2. Run static analysis tools:
+   - **knip** for dead code detection
+   - **FTA** for complexity metrics
+   - **eslint-plugin-sonarjs** for code smells
+   - **dependency-cruiser** for architecture issues
+3. Analyze results against thresholds
+4. Create git worktree at `.worktree/kiss-${timestamp}`
+5. Apply proposed simplifications in worktree
+6. Generate diff and summary
+7. Report back to Claude Code with structured findings
+
+**Agent will NOT:**
+
+- Directly modify files in main working tree
+- Commit changes automatically
+- Push changes to remote
+- Delete any code without explicit permission
+
+## Phase 2: Review Agent Findings
+
+**Claude Code receives agent report and validates findings:**
+
+### 2.1 Parse Agent Report
+
+Extract from agent response:
+
+- **Issues found**: List of over-engineering issues with severity
+- **Worktree location**: Path to worktree with proposed changes
+- **Diff summary**: Overview of proposed changes
+- **Metrics**: Complexity scores, dead code count, etc.
+
+### 2.2 Validate Findings Against KISS Principles
+
+Claude Code re-reviews the proposed changes using the same KISS principles:
+
+**Review checklist:**
+
+- [ ] Are simplifications actually simpler? (No over-simplification)
+- [ ] Do changes preserve functionality? (No behavior changes)
+- [ ] Are naming improvements clearer? (Not just shorter)
+- [ ] Does refactoring reduce cognitive complexity? (Measurable improvement)
+- [ ] Are dead code removals safe? (No false positives)
+
+**If issues found in agent's recommendations:**
+
+```text
+Agent proposed removing function X, but it's used in tests.
+→ Request agent to re-analyze with test file context
+
+Agent suggested renaming Y to Z, but Z is less descriptive.
+→ Request alternative name that balances brevity and clarity
+```
+
+### 2.3 Request Refinements (if needed)
+
+If Claude Code identifies issues with agent's recommendations:
+
+```typescript
+// Re-invoke agent with feedback
+await Task({
+  subagent_type: "kiss-simplifier",
+  description: "Refine KISS analysis based on feedback",
+  prompt: `Review and refine previous analysis based on feedback:
+
+Previous findings: [agent report]
+
+Feedback:
+${feedback}
+
+Update worktree with refined changes and report back.`,
+});
+```
+
+Repeat until Claude Code is satisfied with the analysis quality.
+
+## Phase 3: Generate KISS Report
+
+**Create `.kiss.local.md` with comprehensive findings:**
+
+````markdown
+# KISS Analysis Report
+
+**Generated:** [timestamp ISO]
+**Scope:** [analyzed scope]
+**Mode:** [file | directory | pattern | diff]
+**Worktree:** `.worktree/kiss-[timestamp]`
+**Agent:** kiss-simplifier
+**Reviewed by:** Claude Code
+
+---
+
+## Executive Summary
+
+**Total Issues:** [count]
+
+- 🔴 Critical: [count] (Blocking complexity)
+- 🟠 High: [count] (Significant over-engineering)
+- 🟡 Medium: [count] (Minor improvements)
+- 🟢 Low: [count] (Nice-to-have)
+
+**Potential Impact:**
+
+- **Lines removed:** [count]
+- **Complexity reduction:** [score improvement]
+- **Dead code eliminated:** [count] exports/files
+
+**Overall Assessment:** [summary]
+
+---
+
+## Detailed Findings
+
+### 🔴 Critical Issues (Must Fix)
+
+#### 1. [Issue Title] - [File:Line]
+
+**Category:** [Dead Code | Complexity | Architecture | AI Pattern | Legacy]
+
+**Severity:** Critical
+
+**Current Code:**
+
+```typescript
+[code snippet showing issue]
+```
+
+**Problem:**
+[Explanation of why this is over-engineered]
+
+**Proposed Solution:**
+
+```typescript
+[simplified code from worktree]
+```
+
+**Impact:**
+
+- Complexity: [before] → [after] ([percentage] reduction)
+- Lines: [before] → [after] ([-X] lines)
+
+**Location in worktree:** `.worktree/kiss-[timestamp]/[file-path]`
+
+---
+
+[Repeat for each critical issue]
+
+### 🟠 High Priority Issues
+
+[Same structure as critical]
+
+### 🟡 Medium Priority Issues
+
+[Same structure as critical]
+
+### 🟢 Low Priority Issues
+
+[Same structure as critical]
+
+---
+
+## Metrics Summary
+
+### Complexity Analysis (FTA)
+
+| File    | Before  | After   | Improvement |
+| ------- | ------- | ------- | ----------- |
+| [file1] | [score] | [score] | [delta]%    |
+| [file2] | [score] | [score] | [delta]%    |
+
+### Dead Code Detection (knip)
+
+- **Unused exports:** [count] found
+  - Functions: [count]
+  - Types: [count]
+  - Classes: [count]
+- **Unused files:** [count] found
+- **Unused dependencies:** [count] found
+
+### Architecture Issues (dependency-cruiser)
+
+- **Circular dependencies:** [count]
+- **Layer violations:** [count]
+- **Orphaned modules:** [count]
+
+### Code Smells (eslint-plugin-sonarjs)
+
+- **High cognitive complexity:** [count] functions
+- **Duplicate code:** [count] instances
+- **God objects:** [count] files (>500 LOC)
+
+---
+
+## Worktree Changes Overview
+
+**Worktree location:** `.worktree/kiss-[timestamp]`
+
+**Files modified:** [count]
+**Lines added:** [count]
+**Lines removed:** [count]
+**Net change:** [-X] lines
+
+**Diff summary:**
+
+```diff
+[High-level diff showing key changes]
+```
+
+**To review changes:**
+
+```bash
+# View full diff
+git -C .worktree/kiss-[timestamp] diff HEAD
+
+# Compare specific file
+git -C .worktree/kiss-[timestamp] diff HEAD -- [file]
+
+# Browse worktree
+cd .worktree/kiss-[timestamp]
+```
+
+---
+
+## Recommendations
+
+### Immediate Actions (Critical Issues)
+
+1. **[Action 1]**
+   - Why: [rationale]
+   - Impact: [business/technical benefit]
+   - Effort: [estimation]
+
+2. **[Action 2]**
+   [Same structure]
+
+### Short-term Improvements (High Priority)
+
+[Same structure as immediate actions]
+
+### Long-term Enhancements (Medium/Low Priority)
+
+[Same structure as immediate actions]
+
+---
+
+## Next Steps
+
+You have several options for proceeding with these findings:
+
+### Option 1: Accept Worktree Changes
+
+Review and apply changes from the worktree:
+
+```bash
+# Review changes in worktree
+cd .worktree/kiss-[timestamp]
+
+# Copy specific files back to main tree
+cp [file] ../../[file]
+
+# Or merge all changes
+git -C .worktree/kiss-[timestamp] format-patch HEAD~1
+git am < .worktree/kiss-[timestamp]/0001-*.patch
+
+# Clean up worktree when done
+git worktree remove .worktree/kiss-[timestamp]
+```
+
+### Option 2: Debate and Refine
+
+If you disagree with any recommendations:
+
+```text
+/kiss [scope] --compare
+
+Review the differences and provide feedback.
+Claude Code will re-invoke the agent with your feedback.
+```
+
+### Option 3: Convert to Tasks
+
+Create Task Master tasks for systematic remediation:
+
+```text
+/task:add "Simplify authentication module per KISS analysis"
+  - Reference: .kiss.local.md#auth-complexity
+  - Priority: High
+  - Complexity: Medium
+
+/task:add "Remove dead code identified in utils/"
+  - Reference: .kiss.local.md#dead-code-utils
+  - Priority: Medium
+  - Complexity: Low
+```
+
+### Option 4: Convert to Bugs
+
+For critical issues blocking development:
+
+```text
+/bug "God object UserService exceeds 800 LOC"
+  - Reference: .kiss.local.md#god-object-userservice
+  - Priority: High
+  - Impact: Maintenance burden, testing difficulty
+
+/bug "Circular dependency between API and UI layers"
+  - Reference: .kiss.local.md#circular-deps
+  - Priority: Critical
+  - Impact: Build failures, refactoring blocked
+```
+
+### Option 5: Staged Approach
+
+Combine approaches for large refactorings:
+
+1. **Week 1**: Fix critical issues (accept worktree changes)
+2. **Week 2**: Create tasks for high-priority improvements
+3. **Week 3**: Address medium-priority issues incrementally
+4. **Week 4**: Review and document exceptions for low-priority items
+
+---
+
+## Comparison with Previous Report
+
+[Only if --compare used]
+
+### Changes Since Last Analysis ([date])
+
+**New issues identified:** [count]
+**Issues resolved:** [count]
+**Issues regressed:** [count]
+
+### Metric Trends
+
+| Metric          | Previous | Current | Trend |
+| --------------- | -------- | ------- | ----- |
+| Avg complexity  | [score]  | [score] | [↑↓→] |
+| Dead code count | [count]  | [count] | [↑↓→] |
+| God objects     | [count]  | [count] | [↑↓→] |
+
+### Status Changes
+
+**Improved:**
+
+- [Issue that was fixed]
+
+**Regressed:**
+
+- [Issue that got worse]
+
+**New:**
+
+- [Newly identified issue]
+
+---
+
+## Analysis Configuration
+
+**Tools used:**
+
+- knip v[version] (dead code detection)
+- fta-cli v[version] (complexity analysis)
+- eslint-plugin-sonarjs v[version] (code smells)
+- dependency-cruiser v[version] (architecture)
+
+**Thresholds:**
+
+- Cyclomatic complexity: >15
+- Cognitive complexity: >20
+- FTA score: <60
+- File size: >500 LOC
+
+**Excluded paths:**
+
+- `node_modules/**`
+- `dist/**`
+- `**/*.test.ts`
+- `**/*.d.ts`
+
+---
+
+## Agent Performance
+
+**Analysis time:** [duration]
+**Files analyzed:** [count]
+**Issues found:** [count]
+**Changes proposed:** [count] files
+
+**Agent effectiveness:**
+
+- True positives: [count/count] ([percentage]%)
+- False positives: [count] (refined by Claude Code)
+- Suggestions accepted: [count/count] ([percentage]%)
+
+---
+
+## References
+
+- **KISS Principles:** `detecting-overengineered-code.local.md`
+- **Agent Documentation:** `docs/agents/kiss-simplifier.md`
+- **Command Documentation:** `docs/commands/architect/kiss.md`
+- **Clean Architecture:** `docs/commands/architect/clean.md` (Complementary architectural analysis)
+- **Worktree Location:** `.worktree/kiss-[timestamp]`
+
+---
+
+**Report generated by:** KISS Simplifier Agent (reviewed by Claude Code)
+**Report location:** `.kiss.local.md`
+**Execution time:** [total duration]
+````
+
+## Phase 4: Present Results to User
+
+### 4.1 Write Report to File
+
+```bash
+# Write report to .kiss.local.md
+cat > .kiss.local.md <<EOF
+[Generated report from Phase 3]
+EOF
+```
+
+### 4.2 Open in Editor
+
+```bash
+# Open report in VS Code
+code .kiss.local.md
+```
+
+### 4.3 Console Summary
+
+Print concise summary to console:
+
+```text
+🎯 KISS Analysis Complete
+
+Scope: [analyzed scope]
+Issues found: [total count]
+  🔴 Critical: [count]
+  🟠 High: [count]
+  🟡 Medium: [count]
+  🟢 Low: [count]
+
+Potential improvements:
+  - Remove [count] lines of dead code
+  - Reduce complexity by [percentage]%
+  - Fix [count] architecture violations
+
+Worktree created: .worktree/kiss-[timestamp]
+Report: .kiss.local.md (opened in editor)
+
+Next steps:
+  1. Review findings in .kiss.local.md
+  2. Check worktree diff: cd .worktree/kiss-[timestamp] && git diff HEAD
+  3. Choose action:
+     - Accept changes (copy from worktree)
+     - Debate findings (/kiss --compare)
+     - Convert to tasks (/task:add <description>)
+     - Convert to bugs (/bug <summary>)
+
+Questions?
+  - View all changes: git -C .worktree/kiss-[timestamp] diff HEAD
+  - Review specific file: git -C .worktree/kiss-[timestamp] show HEAD:[file]
+  - Remove worktree: git worktree remove .worktree/kiss-[timestamp]
+```
+
+### 4.4 Interactive Prompts
+
+Ask user for next action:
+
+```text
+What would you like to do next?
+
+1. Review worktree changes in detail
+2. Accept all worktree changes
+3. Accept specific files from worktree
+4. Debate findings and refine
+5. Convert critical issues to tasks
+6. Convert critical issues to bugs
+7. Clean up worktree and exit
+
+Enter choice [1-7]:
+```
+
+**Handle user responses:**
+
+**Choice 1: Review worktree changes**
+
+```bash
+cd .worktree/kiss-[timestamp]
+git diff HEAD --stat
+git diff HEAD
+```
+
+**Choice 2: Accept all worktree changes**
+
+```bash
+# Confirm with user first
+echo "⚠️  This will overwrite files in your main working tree."
+echo "   Worktree: .worktree/kiss-[timestamp]"
+echo "   Files affected: [count]"
+read -p "Continue? [y/N] " confirm
+
+if [[ "$confirm" == "y" ]]; then
+  # Copy files from worktree
+  git -C .worktree/kiss-[timestamp] diff --name-only HEAD | while read file; do
+    cp ".worktree/kiss-[timestamp]/$file" "$file"
+  done
+  echo "✓ Changes applied. Review with 'git diff'"
+fi
+```
+
+**Choice 3: Accept specific files**
+
+```bash
+# Show list of changed files
+echo "Select files to apply (space-separated indices):"
+git -C .worktree/kiss-[timestamp] diff --name-only HEAD | nl
+read -p "Files: " selections
+
+# Copy selected files
+for idx in $selections; do
+  file=$(git -C .worktree/kiss-[timestamp] diff --name-only HEAD | sed -n "${idx}p")
+  cp ".worktree/kiss-[timestamp]/$file" "$file"
+  echo "✓ Applied: $file"
+done
+```
+
+**Choice 4: Debate findings**
+
+```bash
+echo "Which findings do you disagree with? (Reference by issue number from report)"
+read -p "Issue numbers: " issues
+echo "What are your concerns?"
+read -p "Feedback: " feedback
+
+# Re-invoke agent with feedback (Phase 2.3)
+```
+
+**Choice 5: Convert to tasks**
+
+```bash
+echo "Converting critical and high-priority issues to Task Master tasks..."
+
+# Parse critical issues from report
+# Create tasks using /task:add for each
+
+/task:add "Simplify [module] per KISS analysis" \
+  --priority high \
+  --reference .kiss.local.md#issue-1
+
+echo "✓ Created [count] tasks. View with /task:status"
+```
+
+**Choice 6: Convert to bugs**
+
+```bash
+echo "Converting critical issues to bugs..."
+
+# Parse critical issues from report
+# Create bugs using /bug for each
+
+/bug "Critical complexity in [file] - [summary]"
+# Reference: .kiss.local.md#issue-1
+
+echo "✓ Created [count] bugs. View in .bugs.local.md"
+```
+
+**Choice 7: Clean up and exit**
+
+```bash
+echo "Cleaning up worktree..."
+git worktree remove .worktree/kiss-[timestamp]
+echo "✓ Worktree removed. Report saved to .kiss.local.md"
+```
+
+## Error Handling
+
+**KISS principles file missing:**
+
+- Error: "❌ Cannot find detecting-overengineered-code.local.md. This file contains KISS principles for analysis."
+- Exit with status 1
+
+**No files in scope:**
+
+- Warning: "⚠️ No files found matching scope: [scope]"
+- Exit with status 0
+
+**Agent fails to respond:**
+
+- Error: "❌ KISS Simplifier agent failed to complete analysis."
+- Show agent error message
+- Exit with status 2
+
+**Worktree creation fails:**
+
+- Error: "❌ Cannot create git worktree. Ensure git is available and working tree is clean."
+- Suggestion: "Run 'git status' to check for conflicts"
+- Exit with status 3
+
+**Static analysis tools missing:**
+
+- Warning: "⚠️ Some analysis tools are not installed: [list]"
+- Suggestion: "Install missing tools: bun add -D [tools]"
+- Continue with available tools
+
+**Git not available:**
+
+- Error: "❌ Git is required for worktree functionality."
+- Exit with status 4
+
+**Invalid comparison:**
+
+- Warning: "⚠️ --compare flag used but .kiss.local.md not found. Cannot compare."
+- Continue without comparison
+
+## Exit Codes
+
+- 0: Analysis completed successfully
+- 1: Missing required files (KISS principles)
+- 2: Agent execution failure
+- 3: Worktree creation failure
+- 4: Git not available
+- 5: User canceled operation
+
+## Quick Reference
+
+**Common workflows:**
+
+```bash
+# After seeing complexity warnings
+/kiss src/modules/auth.ts        # Analyze specific file
+/kiss src/modules/               # Analyze directory
+
+# Before committing
+/kiss                             # Analyze git-changed files
+/kiss --strict                    # Fail on threshold violations
+
+# Review and refine
+/kiss --compare                   # Compare with previous analysis
+
+# Apply changes
+/kiss --apply                     # Create worktree and apply changes (still requires review)
+```
+
+**Mode summary:**
+
+- File path → Analyze single file
+- Directory path → Analyze all files in directory
+- Pattern → Analyze files matching glob pattern
+- No scope / `--diff` → Analyze git-changed files only
+
+**Integration with existing workflows:**
+
+```bash
+# Option 1: Accept changes directly
+/kiss src/
+# Review .kiss.local.md
+# Accept changes from worktree
+
+# Option 2: Convert to structured work
+/kiss src/
+# Review findings
+/task:add "Simplify auth module per KISS#1"
+/bug "Critical complexity in UserService"
+
+# Option 3: Iterative refinement
+/kiss src/
+# Review and provide feedback
+/kiss src/ --compare  # Re-analyze with refinements
+```