@atlashub/smartstack-cli 3.39.0 → 3.40.0

package/templates/skills/review-code/references/code-quality-metrics.md

@@ -1,174 +1,174 @@
-<overview>
-Quantitative code quality metrics for informed review decisions. Includes cognitive complexity, cyclomatic complexity, maintainability index, and technical debt indicators.
-</overview>
-
-<cognitive_complexity>
-<definition>
-**What it measures**: Mental effort required to understand code
-</definition>
-
-<targets>
-Target complexity levels:
-
-- Per function: <15 (ideal <10)
-- Per module: <50
-- Per file: <100
-</targets>
-
-<complexity_factors>
-Factors that increase complexity:
-
-- Each nesting level (+1 per level)
-- Logical operators (&&, ||)
-- Recursion
-- Breaks in linear flow (break, continue, goto)
-</complexity_factors>
-
-<reduction_example>
-Reducing cognitive complexity:
-
-```javascript
-// HIGH COMPLEXITY (nested conditionals)
-function process(data) {
-  if (data) {
-    if (data.valid) {
-      if (data.items.length > 0) {
-        for (const item of data.items) {
-          if (item.active) {
-            // process
-          }
-        }
-      }
-    }
-  }
-}
-
-// LOW COMPLEXITY (guard clauses + extraction)
-function process(data) {
-  if (!data?.valid) return;
-  if (!data.items?.length) return;
-
-  processActiveItems(data.items);
-}
-
-function processActiveItems(items) {
-  const active = items.filter(item => item.active);
-  active.forEach(processItem);
-}
-```
-</reduction_example>
-</cognitive_complexity>
-
-<cyclomatic_complexity>
-<definition>
-**What it measures**: Number of independent paths through code
-</definition>
-
-<formula>
-**Formula**: 1 + (if + while + for + case + catch + && + ||)
-</formula>
-
-<targets>
-| Score | Risk | Action |
-|-------|------|--------|
-| 1-4 | Low | Good |
-| 5-7 | Moderate | Consider simplifying |
-| 8-10 | High | Refactor recommended |
-| >10 | Very High | Must refactor |
-</targets>
-</cyclomatic_complexity>
-
-<function_size_metrics>
-| Metric | Target | Warning | Critical |
-|--------|--------|---------|----------|
-| Lines | <20 | >30 | >50 |
-| Parameters | ≤3 | 4 | >5 |
-| Nesting depth | ≤2 | 3 | >3 |
-| Return statements | 1-2 | 3-4 | >4 |
-</function_size_metrics>
-
-<maintainability_index>
-<formula>
-Microsoft's formula:
-
-```
-MI = MAX(0, (171 - 5.2*ln(HalsteadVolume) - 0.23*CC - 16.2*ln(LOC)) * 100/171)
-```
-</formula>
-
-<interpretation>
-| Score | Maintainability |
-|-------|-----------------|
-| 80-100 | High - easy to maintain |
-| 60-79 | Moderate - some concerns |
-| 40-59 | Low - refactoring recommended |
-| <40 | Very Low - significant refactoring needed |
-</interpretation>
-</maintainability_index>
-
-<technical_debt_indicators>
-| Indicator | Healthy | Warning |
-|-----------|---------|---------|
-| Code duplication | <5% | >10% |
-| Test coverage | >80% | <60% |
-| Cyclomatic complexity avg | <5 | >8 |
-| TODO/FIXME count | Stable | Growing |
-| Dependency age | <6 months | >12 months |
-</technical_debt_indicators>
-
-<code_churn>
-<definition>
-**What it measures**: Frequency of code changes
-</definition>
-
-<warning_signs>
-Signs of problematic churn:
-
-- Same file changed in >50% of recent commits
-- High churn + low test coverage = risk
-- Late-project churn indicates instability
-</warning_signs>
-</code_churn>
-
-<review_thresholds>
-<must_comment>
-Always comment on:
-
-- Function complexity >15
-- Nesting >3 levels
-- Function >50 lines
-- >3 parameters without object
-</must_comment>
-
-<consider_commenting>
-Consider commenting on:
-
-- Duplicated blocks >10 lines
-- Method doing multiple things
-- Unclear naming
-</consider_commenting>
-
-<dont_comment>
-Skip commenting on:
-
-- Slightly suboptimal but working code
-- Style preferences
-- Minor naming improvements
-</dont_comment>
-</review_thresholds>
-
-<measurement_tools>
-| Language | Tool |
-|----------|------|
-| JavaScript/TypeScript | ESLint (complexity rules), SonarQube |
-| Python | Radon, Pylint |
-| Java | SonarQube, PMD |
-| Go | gocyclo, golangci-lint |
-| General | SonarQube, CodeClimate |
-</measurement_tools>
-
-<sources>
-- [SonarQube Cognitive Complexity](https://www.sonarsource.com/docs/CognitiveComplexity.pdf)
-- [Microsoft Maintainability Index](https://learn.microsoft.com/en-us/visualstudio/code-quality/code-metrics-maintainability-index-range-and-meaning)
-- [Cyclomatic Complexity](https://en.wikipedia.org/wiki/Cyclomatic_complexity)
-</sources>
+<overview>
+Quantitative code quality metrics for informed review decisions. Includes cognitive complexity, cyclomatic complexity, maintainability index, and technical debt indicators.
+</overview>
+
+<cognitive_complexity>
+<definition>
+**What it measures**: Mental effort required to understand code
+</definition>
+
+<targets>
+Target complexity levels:
+
+- Per function: <15 (ideal <10)
+- Per module: <50
+- Per file: <100
+</targets>
+
+<complexity_factors>
+Factors that increase complexity:
+
+- Each nesting level (+1 per level)
+- Logical operators (&&, ||)
+- Recursion
+- Breaks in linear flow (break, continue, goto)
+</complexity_factors>
+
+<reduction_example>
+Reducing cognitive complexity:
+
+```javascript
+// HIGH COMPLEXITY (nested conditionals)
+function process(data) {
+  if (data) {
+    if (data.valid) {
+      if (data.items.length > 0) {
+        for (const item of data.items) {
+          if (item.active) {
+            // process
+          }
+        }
+      }
+    }
+  }
+}
+
+// LOW COMPLEXITY (guard clauses + extraction)
+function process(data) {
+  if (!data?.valid) return;
+  if (!data.items?.length) return;
+
+  processActiveItems(data.items);
+}
+
+function processActiveItems(items) {
+  const active = items.filter(item => item.active);
+  active.forEach(processItem);
+}
+```
+</reduction_example>
+</cognitive_complexity>
+
+<cyclomatic_complexity>
+<definition>
+**What it measures**: Number of independent paths through code
+</definition>
+
+<formula>
+**Formula**: 1 + (if + while + for + case + catch + && + ||)
+</formula>
+
+<targets>
+| Score | Risk | Action |
+|-------|------|--------|
+| 1-4 | Low | Good |
+| 5-7 | Moderate | Consider simplifying |
+| 8-10 | High | Refactor recommended |
+| >10 | Very High | Must refactor |
+</targets>
+</cyclomatic_complexity>
+
+<function_size_metrics>
+| Metric | Target | Warning | Critical |
+|--------|--------|---------|----------|
+| Lines | <20 | >30 | >50 |
+| Parameters | ≤3 | 4 | >5 |
+| Nesting depth | ≤2 | 3 | >3 |
+| Return statements | 1-2 | 3-4 | >4 |
+</function_size_metrics>
+
+<maintainability_index>
+<formula>
+Microsoft's formula:
+
+```
+MI = MAX(0, (171 - 5.2*ln(HalsteadVolume) - 0.23*CC - 16.2*ln(LOC)) * 100/171)
+```
+</formula>
+
+<interpretation>
+| Score | Maintainability |
+|-------|-----------------|
+| 80-100 | High - easy to maintain |
+| 60-79 | Moderate - some concerns |
+| 40-59 | Low - refactoring recommended |
+| <40 | Very Low - significant refactoring needed |
+</interpretation>
+</maintainability_index>
+
+<technical_debt_indicators>
+| Indicator | Healthy | Warning |
+|-----------|---------|---------|
+| Code duplication | <5% | >10% |
+| Test coverage | >80% | <60% |
+| Cyclomatic complexity avg | <5 | >8 |
+| TODO/FIXME count | Stable | Growing |
+| Dependency age | <6 months | >12 months |
+</technical_debt_indicators>
+
+<code_churn>
+<definition>
+**What it measures**: Frequency of code changes
+</definition>
+
+<warning_signs>
+Signs of problematic churn:
+
+- Same file changed in >50% of recent commits
+- High churn + low test coverage = risk
+- Late-project churn indicates instability
+</warning_signs>
+</code_churn>
+
+<review_thresholds>
+<must_comment>
+Always comment on:
+
+- Function complexity >15
+- Nesting >3 levels
+- Function >50 lines
+- >3 parameters without object
+</must_comment>
+
+<consider_commenting>
+Consider commenting on:
+
+- Duplicated blocks >10 lines
+- Method doing multiple things
+- Unclear naming
+</consider_commenting>
+
+<dont_comment>
+Skip commenting on:
+
+- Slightly suboptimal but working code
+- Style preferences
+- Minor naming improvements
+</dont_comment>
+</review_thresholds>
+
+<measurement_tools>
+| Language | Tool |
+|----------|------|
+| JavaScript/TypeScript | ESLint (complexity rules), SonarQube |
+| Python | Radon, Pylint |
+| Java | SonarQube, PMD |
+| Go | gocyclo, golangci-lint |
+| General | SonarQube, CodeClimate |
+</measurement_tools>
+
+<sources>
+- [SonarQube Cognitive Complexity](https://www.sonarsource.com/docs/CognitiveComplexity.pdf)
+- [Microsoft Maintainability Index](https://learn.microsoft.com/en-us/visualstudio/code-quality/code-metrics-maintainability-index-range-and-meaning)
+- [Cyclomatic Complexity](https://en.wikipedia.org/wiki/Cyclomatic_complexity)
+</sources>

package/templates/skills/review-code/references/feedback-patterns.md

@@ -1,149 +1,149 @@
-<overview>
-Code review feedback patterns based on research from Google, Microsoft, and academic studies on effective code review communication.
-</overview>
-
-<what_why_how_pattern>
-Every valuable comment includes three components:
-
-1. **What**: The specific issue
-2. **Why**: Why it matters
-3. **How**: Concrete fix or direction
-
-<good_example>
-```
-[BLOCKING] SQL injection vulnerability at line 34.
-The query uses string concatenation with user input, allowing attackers to modify the query.
-Fix: Use parameterized query: db.query('SELECT * FROM users WHERE id = ?', [userId])
-```
-</good_example>
-
-<bad_example>
-```
-This query looks unsafe.
-```
-</bad_example>
-</what_why_how_pattern>
-
-<priority_labels>
-Use consistent labels so authors know severity:
-
-| Label | Meaning | Merge? |
-|-------|---------|--------|
-| `[BLOCKING]` | Must fix - security, bugs, missing requirements | No |
-| `[CRITICAL]` | Strongly recommended - architecture, major issues | Discuss |
-| `[SUGGESTION]` | Would improve code - not required | Yes |
-| `[NIT]` | Minor preference - skip if busy | Yes |
-| `[QUESTION]` | Need clarification - not blocking | Yes |
-</priority_labels>
-
-<feedback_value>
-<high_value>
-High-value feedback (36-43% implementation rate):
-
-- Security vulnerabilities with exploit scenario
-- Logic errors with failing test case
-- Missing error handling with consequences
-- Performance issues with measurements
-</high_value>
-
-<wasteful>
-Wasteful feedback (damages team dynamics):
-
-- Style preferences covered by linters
-- Renaming suggestions without clear benefit
-- "I would do it differently" without why
-- Comments on code outside the diff
-</wasteful>
-</feedback_value>
-
-<communication_patterns>
-<collaborative_framing>
-Use collaborative, question-based framing:
-
-```
-✓ "Have you considered using a Map here for O(1) lookup?"
-✓ "This could throw if user is null - should we add a check?"
-✓ "I'm not sure I understand this logic - could you explain?"
-
-✗ "You need to fix this."
-✗ "This is wrong."
-✗ "Obviously this should be..."
-```
-</collaborative_framing>
-
-<avoid_belittling>
-Remove belittling words: "just", "simply", "obviously", "easy", "only"
-
-```
-✗ "Just add a null check"
-✗ "This is obviously wrong"
-✓ "Add a null check for user.profile"
-```
-</avoid_belittling>
-</communication_patterns>
-
-<merge_decisions>
-<block_merge>
-Block merge for:
-
-- Security vulnerabilities (any severity)
-- Logic bugs that affect functionality
-- Missing required tests
-- Breaking API changes without migration
-</block_merge>
-
-<approve_with_comments>
-Approve with comments for:
-
-- Suggestions for future improvement
-- Minor refactoring opportunities
-- Documentation improvements
-- Style preferences (should be in linter)
-</approve_with_comments>
-
-<approve_clean>
-Approve cleanly when:
-
-- Code meets requirements
-- Tests pass
-- No security issues
-- Follows project conventions
-</approve_clean>
-</merge_decisions>
-
-<avoiding_nitpick_culture>
-**Research finding**: Nitpicking damages team relationships more than it improves code quality. Developers become defensive and less receptive to legitimate feedback.
-
-<solution>
-1. Automate style enforcement (linters, formatters)
-2. Block CI on lint failures, not PR comments
-3. Reserve human review for logic and design
-4. Mark true nitpicks with `[NIT]` prefix
-5. Limit to 3-5 critical items per review
-</solution>
-</avoiding_nitpick_culture>
-
-<review_efficiency>
-<google_data>
-Google's review data shows:
-
-- 90% of reviews: <10 files changed
-- Average turnaround: 4 hours
-- 75% need only one reviewer
-</google_data>
-
-<best_practices>
-Efficiency best practices:
-
-- Small PRs get better feedback
-- Review within 4 hours if possible
-- Focus on changed code only
-- One pass, thorough, then done
-</best_practices>
-</review_efficiency>
-
-<sources>
-- [Google Code Review Guide](https://google.github.io/eng-practices/review/)
-- [Microsoft Reviewer Guidance](https://microsoft.github.io/code-with-engineering-playbook/code-reviews/)
-- [Conventional Comments](https://conventionalcomments.org/)
-</sources>
+<overview>
+Code review feedback patterns based on research from Google, Microsoft, and academic studies on effective code review communication.
+</overview>
+
+<what_why_how_pattern>
+Every valuable comment includes three components:
+
+1. **What**: The specific issue
+2. **Why**: Why it matters
+3. **How**: Concrete fix or direction
+
+<good_example>
+```
+[BLOCKING] SQL injection vulnerability at line 34.
+The query uses string concatenation with user input, allowing attackers to modify the query.
+Fix: Use parameterized query: db.query('SELECT * FROM users WHERE id = ?', [userId])
+```
+</good_example>
+
+<bad_example>
+```
+This query looks unsafe.
+```
+</bad_example>
+</what_why_how_pattern>
+
+<priority_labels>
+Use consistent labels so authors know severity:
+
+| Label | Meaning | Merge? |
+|-------|---------|--------|
+| `[BLOCKING]` | Must fix - security, bugs, missing requirements | No |
+| `[CRITICAL]` | Strongly recommended - architecture, major issues | Discuss |
+| `[SUGGESTION]` | Would improve code - not required | Yes |
+| `[NIT]` | Minor preference - skip if busy | Yes |
+| `[QUESTION]` | Need clarification - not blocking | Yes |
+</priority_labels>
+
+<feedback_value>
+<high_value>
+High-value feedback (36-43% implementation rate):
+
+- Security vulnerabilities with exploit scenario
+- Logic errors with failing test case
+- Missing error handling with consequences
+- Performance issues with measurements
+</high_value>
+
+<wasteful>
+Wasteful feedback (damages team dynamics):
+
+- Style preferences covered by linters
+- Renaming suggestions without clear benefit
+- "I would do it differently" without why
+- Comments on code outside the diff
+</wasteful>
+</feedback_value>
+
+<communication_patterns>
+<collaborative_framing>
+Use collaborative, question-based framing:
+
+```
+✓ "Have you considered using a Map here for O(1) lookup?"
+✓ "This could throw if user is null - should we add a check?"
+✓ "I'm not sure I understand this logic - could you explain?"
+
+✗ "You need to fix this."
+✗ "This is wrong."
+✗ "Obviously this should be..."
+```
+</collaborative_framing>
+
+<avoid_belittling>
+Remove belittling words: "just", "simply", "obviously", "easy", "only"
+
+```
+✗ "Just add a null check"
+✗ "This is obviously wrong"
+✓ "Add a null check for user.profile"
+```
+</avoid_belittling>
+</communication_patterns>
+
+<merge_decisions>
+<block_merge>
+Block merge for:
+
+- Security vulnerabilities (any severity)
+- Logic bugs that affect functionality
+- Missing required tests
+- Breaking API changes without migration
+</block_merge>
+
+<approve_with_comments>
+Approve with comments for:
+
+- Suggestions for future improvement
+- Minor refactoring opportunities
+- Documentation improvements
+- Style preferences (should be in linter)
+</approve_with_comments>
+
+<approve_clean>
+Approve cleanly when:
+
+- Code meets requirements
+- Tests pass
+- No security issues
+- Follows project conventions
+</approve_clean>
+</merge_decisions>
+
+<avoiding_nitpick_culture>
+**Research finding**: Nitpicking damages team relationships more than it improves code quality. Developers become defensive and less receptive to legitimate feedback.
+
+<solution>
+1. Automate style enforcement (linters, formatters)
+2. Block CI on lint failures, not PR comments
+3. Reserve human review for logic and design
+4. Mark true nitpicks with `[NIT]` prefix
+5. Limit to 3-5 critical items per review
+</solution>
+</avoiding_nitpick_culture>
+
+<review_efficiency>
+<google_data>
+Google's review data shows:
+
+- 90% of reviews: <10 files changed
+- Average turnaround: 4 hours
+- 75% need only one reviewer
+</google_data>
+
+<best_practices>
+Efficiency best practices:
+
+- Small PRs get better feedback
+- Review within 4 hours if possible
+- Focus on changed code only
+- One pass, thorough, then done
+</best_practices>
+</review_efficiency>
+
+<sources>
+- [Google Code Review Guide](https://google.github.io/eng-practices/review/)
+- [Microsoft Reviewer Guidance](https://microsoft.github.io/code-with-engineering-playbook/code-reviews/)
+- [Conventional Comments](https://conventionalcomments.org/)
+</sources>