ai-qakit 1.0.0

package/templates/.claude/commands/devkit/create-test.md

@@ -0,0 +1,165 @@
+---
+description: Generate tests to achieve 99% coverage for a file
+argument-hint: [file-path]
+allowed-tools: Read, Grep, Bash(test:*, find, ls, cat), Write, Edit, AskUserQuestion, Skill
+---
+
+<!--
+Usage: /create-test [file-path]
+Requires: Test framework configured (Jest/Pytest/Go test/etc.)
+Example: /create-test src/services/auth.service.ts
+Example: /create-test app/models/user.py
+Example: /create-test pkg/handlers/user.go
+-->
+
+**IMPORTANT:** Analyze the skills catalog and activate the skills that are needed for the task during the process.
+
+---
+
+**Report Protocol**: Follow ./.claude/CLAUDE.md "Sub-Agent Report Generation" protocol before spawning subagents.
+
+# Optimize Unit Test Coverage
+
+Generate comprehensive tests for a file targeting 99%+ coverage.
+
+## Input Validation
+
+### Validate File Path ($1)
+
+If $1 not provided:
+  Use AskUserQuestion to ask for file path:
+  - question: "Which file should I generate tests for?"
+  - header: "Target File"
+  - options:
+    - I'll provide the file path
+
+If $1 provided:
+  Check file exists: !`test -f "$1" && echo "EXISTS" || echo "MISSING"`
+
+  If MISSING:
+    - Show error: "File not found: $1"
+    - List similar files that might be intended: !`find . -name "*$(basename "$1")*" -type f 2>/dev/null | head -10`
+    - Use `AskUserQuestion` tool to ask user for correct path
+    - Do not proceed
+
+  If EXISTS:
+    - Proceed with test generation for @$1
+
+## ⚠️ Plan Before Executing
+
+**Always create a structured plan and get user approval before making changes.**
+
+1. Analyze the file and show what tests will be created
+2. Present the test plan with scenarios to cover
+3. Ask for confirmation before writing test files
+4. Never generate tests without user approval
+
+## Important: Ask for Clarification
+
+**If anything is unclear, DO NOT GUESS. Ask the user:**
+
+- "What specific scenarios should I prioritize testing?"
+- "Are there any edge cases specific to this business logic I should know about?"
+- "Should I mock [dependency] or use the real implementation?"
+- "What's the expected behavior when [unclear scenario]?"
+- "Is there existing test setup/fixtures I should use?"
+
+Use AskUserQuestion tool when you need more context before proceeding.
+
+## Step 1: Reference Project Profile
+
+Read @.claude/CLAUDE.md to understand:
+- Testing framework
+- Coverage tool and commands
+- Test directory structure
+- Naming conventions
+- Mock patterns
+
+If `.claude/CLAUDE.md` doesn't exist, run `/init` first.
+
+## Step 2: Analyze Current Coverage
+
+Run coverage report for target file:
+
+!`[coverage command from CLAUDE.md] $1`
+
+Parse coverage output to identify:
+- Current coverage percentage
+- Uncovered lines
+- Uncovered branches
+
+## Step 3: Analyze Implementation
+
+Read @$1 to identify:
+- All public methods/functions
+- Dependencies requiring mocks
+- Branch conditions (if/else, switch, ternary)
+- Error handling paths
+- Edge cases
+- Compound boolean expressions (||, &&)
+
+## Step 4: Review Existing Tests
+
+Find and read existing test file for $1.
+Identify:
+- Already covered scenarios
+- Mock patterns in use
+- Test utilities available
+- Setup/teardown patterns
+
+## Step 5: Generate Missing Tests
+
+Create tests for uncovered code following AAA pattern:
+
+```
+Arrange - Set up test data and mocks
+Act     - Execute the code under test  
+Assert  - Verify the results
+```
+
+**Target these uncovered scenarios:**
+- Happy path variations
+- Empty/null input handling
+- Alternative error paths
+- Edge cases in conditionals
+- Boundary values
+- Exception scenarios
+- Timeout/retry paths
+
+**Use detected naming convention:**
+`should [expected behavior] when [condition]`
+
+## Step 6: Write Test File
+
+Create or update test file following project conventions:
+- Use correct test directory
+- Follow naming pattern from CLAUDE.md
+- Import project's test utilities
+- Use project's mock patterns
+
+## Step 7: Verify Coverage
+
+Run tests and display coverage:
+
+!`[test command] [test-file-path]`
+
+## Step 8: Report Results
+
+Display:
+- Lines covered vs uncovered
+- Branch coverage
+- Any remaining gaps with explanation
+
+**Coverage interpretation:**
+| Coverage | Assessment |
+|----------|------------|
+| < 70% | Needs more tests |
+| 70-80% | Basic coverage |
+| 80-90% | Good coverage |
+| 90-95% | Excellent |
+| 95-99% | Outstanding |
+| 99%+ | Exceptional |
+
+**Note:** 94-95% is often excellent due to coverage tool limitations with compound booleans and defensive code.
+
+Generate tests now for @$1.

package/templates/.claude/commands/devkit/debug.md

@@ -0,0 +1,481 @@
+---
+description: Systematic 7-step debugging methodology for problem solving
+argument-hint: [issue-description] | [error-message] | [ticket-id]
+allowed-tools: Read, Grep, Bash, Write, Edit, AskUserQuestion, Skill
+---
+
+**Report Protocol**: Follow ./.claude/CLAUDE.md "Sub-Agent Report Generation" protocol before spawning subagents.
+
+**IMPORTANT:** Analyze the skills catalog and activate the skills that are needed for the task during the process.
+
+---
+
+# Debug - Systematic Problem Solving
+
+A structured 7-step methodology to identify, analyze, and resolve problems systematically.
+
+## What You Get
+
+- **Structured Methodology** - Prevents random debugging attempts, ensures comprehensive analysis
+- **Evidence-Based Analysis** - Backed by logs, tests, and reproduction steps
+- **Balanced Solutions** - Multiple options with trade-offs and risk assessment
+- **Actionable Plans** - Specific tasks with owners, timelines, and validation criteria
+
+## Use Cases
+
+- **Bug Fixes** - Resolve unexpected behavior or errors
+- **Integration Issues** - Troubleshoot system interactions
+- **Performance Problems** - Analyze and fix slowdowns
+- **Security Concerns** - Investigate and resolve vulnerabilities
+- **Validation** - Verify fixes before deployment
+
+## ⚠️ Plan Before Executing
+
+**Always create a structured plan and get user approval before making changes.**
+
+1. Complete the full 7-step analysis first
+2. Present resolution options with trade-offs
+3. Get explicit approval on chosen approach
+4. Show implementation plan before any changes
+5. Never implement fixes without user approval
+
+## Important: Ask for Clarification
+
+**If anything is unclear, DO NOT GUESS. Ask the user:**
+
+- "Can you share the exact error message or stack trace?"
+- "When did this issue start occurring?"
+- "Is this happening in all environments or just specific ones?"
+- "Were there any recent deployments or changes?"
+- "How many users/requests are affected?"
+
+Use AskUserQuestion tool when you need more context before proceeding.
+
+---
+
+## Step 1: Gather Context
+
+Collect comprehensive information about the issue.
+
+Use AskUserQuestion to gather:
+
+**Question 1: Issue Description**
+- question: "What is happening? Describe the issue briefly."
+- header: "Issue"
+- options:
+  - I'll describe the issue (wait for free text)
+
+**Question 2: Expected Behavior**
+- question: "What should happen instead? What's the expected behavior?"
+- header: "Expected"
+- options:
+  - I'll describe expected behavior (wait for free text)
+
+**Question 3: Error Details**
+- question: "Are there any error messages, logs, or stack traces?"
+- header: "Errors"
+- options:
+  - Yes, I'll share them
+  - No error messages, just unexpected behavior
+  - I need help finding the logs
+
+**Question 4: Recent Changes**
+- question: "Were there any recent changes or deployments related to this?"
+- header: "Changes"
+- options:
+  - Yes, recent deployment
+  - Yes, code changes
+  - Yes, configuration changes
+  - No recent changes
+  - Not sure
+
+**Question 5: Impact Scope**
+- question: "What's the scope of impact?"
+- header: "Impact"
+- options:
+  - All users affected
+  - Some users affected
+  - Single user/request
+  - Specific environment only
+  - Intermittent issue
+
+If user provides issue via $ARGUMENTS, parse it and ask follow-up questions.
+
+### Context Summary
+
+After gathering, summarize:
+
+```
+════════════════════════════════════════════════════════════════════
+                        📋 ISSUE CONTEXT
+════════════════════════════════════════════════════════════════════
+Issue:        [brief description]
+Expected:     [expected behavior]
+Actual:       [current behavior]
+Errors:       [error messages if any]
+Recent Changes: [relevant changes]
+Impact:       [scope and severity]
+Environment:  [where it occurs]
+════════════════════════════════════════════════════════════════════
+```
+
+---
+
+## Step 2: Clarify Reality vs Expectation
+
+Clearly define the gap between current and expected state.
+
+### Observed Behavior
+Document exactly what is happening:
+- Specific symptoms
+- Error messages with timestamps
+- Affected endpoints/components
+- User-reported issues
+
+### Expected Outcome
+Confirm what should happen:
+- Reference requirements or tickets
+- Link to documentation
+- Previous working behavior
+- Acceptance criteria
+
+### Success Criteria
+Define how we'll know the issue is resolved:
+- [ ] [Specific measurable criterion 1]
+- [ ] [Specific measurable criterion 2]
+- [ ] [Test that should pass]
+- [ ] [User scenario that should work]
+
+Use AskUserQuestion if requirements are unclear:
+- question: "Is there a ticket, spec, or documentation that defines the expected behavior?"
+- header: "Reference"
+- options:
+  - Yes, I'll share the reference
+  - No documentation, but I can describe it
+  - Need to check with product/team
+
+---
+
+## Step 3: Reproduce & Isolate
+
+Create reliable reproduction and narrow down the problem.
+
+### Reproducibility Check
+
+Use AskUserQuestion:
+- question: "How consistently can you reproduce this issue?"
+- header: "Reproduce"
+- options:
+  - Always (100% reproducible)
+  - Usually (>50% of the time)
+  - Sometimes (<50% of the time)
+  - Rarely (hard to reproduce)
+  - Haven't tried yet
+
+### Reproduction Steps
+
+Document step-by-step instructions:
+
+```
+REPRODUCTION STEPS:
+1. [First action]
+2. [Second action]
+3. [Action that triggers the issue]
+4. [Observed result]
+
+ENVIRONMENT:
+- Environment: [dev/staging/prod]
+- Browser/Client: [if applicable]
+- User type: [role/permissions]
+- Data conditions: [specific data state]
+```
+
+### Isolation
+
+Narrow down the problem:
+
+```bash
+# Check logs for errors
+grep -i "error\|exception\|fail" [log-file] | tail -50
+
+# Find recent changes to suspected files
+git log --oneline -10 -- [suspected-file]
+
+# Check if issue exists in other environments
+[environment-specific commands]
+```
+
+### Suspected Components
+
+| Component | Likelihood | Evidence |
+|-----------|------------|----------|
+| [Component 1] | High/Medium/Low | [Why suspected] |
+| [Component 2] | High/Medium/Low | [Why suspected] |
+| [Component 3] | High/Medium/Low | [Why suspected] |
+
+### Related Tests
+
+Check if existing tests cover this scenario:
+```bash
+# Find related tests
+grep -r "[related-function]\|[related-feature]" **/*.spec.* **/*.test.*
+```
+
+---
+
+## Step 4: Analyze Potential Causes
+
+Brainstorm and evaluate possible root causes.
+
+### Potential Root Causes
+
+| # | Hypothesis | Evidence For | Evidence Against | Confidence |
+|---|-----------|--------------|------------------|------------|
+| 1 | [Cause hypothesis 1] | [Supporting evidence] | [Contradicting evidence] | High/Med/Low |
+| 2 | [Cause hypothesis 2] | [Supporting evidence] | [Contradicting evidence] | High/Med/Low |
+| 3 | [Cause hypothesis 3] | [Supporting evidence] | [Contradicting evidence] | High/Med/Low |
+
+### Categories to Consider
+
+- **Data Issues**: Invalid data, missing records, data corruption
+- **Configuration**: Environment variables, feature flags, settings
+- **Code Regression**: Recent changes introducing bugs
+- **External Dependencies**: Third-party services, APIs, databases
+- **Infrastructure**: Network, resources, permissions
+- **Race Conditions**: Timing, concurrency, async issues
+
+### Evidence Gathering
+
+```bash
+# Check relevant logs
+[log command]
+
+# Check metrics/monitoring
+[metrics command]
+
+# Check database state
+[database query]
+
+# Check external service status
+[health check command]
+```
+
+### Gaps & Unknowns
+
+Things we need to investigate further:
+- [ ] [Unknown 1 - needs investigation]
+- [ ] [Unknown 2 - need more data]
+- [ ] [Unknown 3 - need expert input]
+
+---
+
+## Step 5: Surface Options
+
+Present multiple resolution approaches with trade-offs.
+
+### Resolution Options
+
+#### Option A: [Quick Fix / Patch]
+
+**Description**: [Brief description of approach]
+
+| Aspect | Details |
+|--------|---------|
+| **Approach** | [What we'll do] |
+| **Pros** | Fast, minimal risk, targeted fix |
+| **Cons** | May not address root cause, could recur |
+| **Effort** | [Low/Medium/High] - [time estimate] |
+| **Risk** | [Low/Medium/High] - [specific risks] |
+| **Verification** | [How to verify it works] |
+
+#### Option B: [Deeper Fix / Refactor]
+
+**Description**: [Brief description of approach]
+
+| Aspect | Details |
+|--------|---------|
+| **Approach** | [What we'll do] |
+| **Pros** | Addresses root cause, improves code quality |
+| **Cons** | More time, higher risk of side effects |
+| **Effort** | [Low/Medium/High] - [time estimate] |
+| **Risk** | [Low/Medium/High] - [specific risks] |
+| **Verification** | [How to verify it works] |
+
+#### Option C: [Rollback / Revert]
+
+**Description**: [Brief description of approach]
+
+| Aspect | Details |
+|--------|---------|
+| **Approach** | [What we'll do] |
+| **Pros** | Immediate relief, buys time |
+| **Cons** | Loses recent changes, temporary |
+| **Effort** | [Low/Medium/High] - [time estimate] |
+| **Risk** | [Low/Medium/High] - [specific risks] |
+| **Verification** | [How to verify it works] |
+
+#### Option D: [Feature Flag / Workaround]
+
+**Description**: [Brief description of approach]
+
+| Aspect | Details |
+|--------|---------|
+| **Approach** | [What we'll do] |
+| **Pros** | Controlled rollout, easy to revert |
+| **Cons** | Adds complexity, temporary solution |
+| **Effort** | [Low/Medium/High] - [time estimate] |
+| **Risk** | [Low/Medium/High] - [specific risks] |
+| **Verification** | [How to verify it works] |
+
+### Recommendation
+
+Based on analysis, recommend: **Option [X]**
+
+Reasoning: [Why this option is best for the situation]
+
+---
+
+## Step 6: Confirm Path Forward
+
+Get agreement on the approach and plan execution.
+
+Use AskUserQuestion:
+- question: "Which resolution approach should we pursue?"
+- header: "Decision"
+- options:
+  - Option A: [Quick Fix]
+  - Option B: [Deeper Fix]
+  - Option C: [Rollback]
+  - Option D: [Feature Flag]
+  - Need more information
+  - Discuss with team first
+
+### Selected Approach Summary
+
+```
+════════════════════════════════════════════════════════════════════
+                     ✅ CONFIRMED RESOLUTION PATH
+════════════════════════════════════════════════════════════════════
+Approach:     [Selected option]
+Effort:       [Time estimate]
+Risk Level:   [Low/Medium/High]
+
+PRE-WORK REQUIRED:
+□ [Pre-requisite 1]
+□ [Pre-requisite 2]
+
+SUCCESS CRITERIA:
+□ [Criterion 1]
+□ [Criterion 2]
+□ [Test that should pass]
+
+VALIDATION PLAN:
+1. [Validation step 1]
+2. [Validation step 2]
+3. [User acceptance if needed]
+
+APPROVALS NEEDED:
+□ [Approval 1 if any]
+□ [Approval 2 if any]
+════════════════════════════════════════════════════════════════════
+```
+
+### Required Coordination
+
+- [ ] Notify: [Teams/people to inform]
+- [ ] Schedule: [Deployment window if needed]
+- [ ] Prepare: [Rollback plan]
+
+---
+
+## Step 7: Next Actions & Tracking
+
+Document specific tasks and follow-up plan.
+
+### Action Items
+
+| # | Task | Owner | Deadline | Status |
+|---|------|-------|----------|--------|
+| 1 | [Implement fix] | [Name] | [Date] | ⏳ Pending |
+| 2 | [Write/update tests] | [Name] | [Date] | ⏳ Pending |
+| 3 | [Code review] | [Name] | [Date] | ⏳ Pending |
+| 4 | [Deploy to staging] | [Name] | [Date] | ⏳ Pending |
+| 5 | [Validate in staging] | [Name] | [Date] | ⏳ Pending |
+| 6 | [Deploy to production] | [Name] | [Date] | ⏳ Pending |
+| 7 | [Monitor post-deploy] | [Name] | [Date] | ⏳ Pending |
+
+### Post-Resolution Tasks
+
+- [ ] Update documentation if needed
+- [ ] Add/update tests to prevent regression
+- [ ] Communicate resolution to stakeholders
+- [ ] Schedule postmortem if significant issue
+- [ ] Update runbook if applicable
+
+### Monitoring Plan
+
+```
+POST-DEPLOYMENT MONITORING:
+- Duration: [How long to monitor]
+- Metrics to watch: [Key metrics]
+- Alerts configured: [Yes/No]
+- Escalation path: [Who to contact if issues]
+```
+
+### Communication Plan
+
+| Audience | Message | Channel | Timing |
+|----------|---------|---------|--------|
+| [Team/Users] | [What to communicate] | [Slack/Email/etc] | [When] |
+
+---
+
+## Final Summary
+
+Display completion summary:
+
+```
+════════════════════════════════════════════════════════════════════
+                    🔧 DEBUG SESSION COMPLETE
+════════════════════════════════════════════════════════════════════
+
+ISSUE: [Brief description]
+
+ROOT CAUSE: [Identified cause]
+
+RESOLUTION: [Chosen approach]
+
+STATUS: Ready for implementation
+
+ACTION ITEMS:
+  1. [First task] - [Owner]
+  2. [Second task] - [Owner]
+  3. [Third task] - [Owner]
+
+SUCCESS CRITERIA:
+  □ [Criterion 1]
+  □ [Criterion 2]
+
+NEXT STEP: [Immediate next action]
+
+════════════════════════════════════════════════════════════════════
+```
+
+Use AskUserQuestion:
+- question: "Ready to proceed with implementation, or need anything else?"
+- header: "Next"
+- options:
+  - Yes, start implementing the fix
+  - Need to investigate more
+  - Need team discussion first
+  - Document this for later
+
+---
+
+## Begin Now
+
+If issue description provided via $ARGUMENTS, start with Step 1 context gathering.
+Otherwise, ask for the issue description to begin the debugging flow.
+
+Ready to help debug. What issue are you facing?
+