specweave 0.22.3 → 0.22.5

package/plugins/specweave/skills/code-standards-analyzer/SKILL.md

@@ -0,0 +1,455 @@
+---
+name: code-standards-analyzer
+description: Coding standards discovery and documentation expert. Analyzes codebase to detect naming conventions, patterns, anti-patterns, and best practices. Generates or updates coding standards documentation in .specweave/docs/internal/governance/. Detects ESLint/Prettier configs, analyzes TypeScript/JavaScript patterns, finds security issues, and creates evidence-based standards with confidence levels. Activates for analyze coding standards, discover conventions, code style analysis, detect patterns, coding guidelines, what are the standards, code quality check, naming conventions, linting rules, best practices analysis, standards audit, code review standards, detect anti-patterns.
+allowed-tools: Read, Grep, Glob, Bash, Write, Edit
+---
+
+# Code Standards Analyzer
+
+**Purpose**: Discover, document, and maintain coding standards from existing codebases using evidence-based analysis.
+
+**Philosophy**: Standards should reflect REALITY (what the code actually does) not ASPIRATIONS (what we wish it did). Measure, then document.
+
+---
+
+## When to Use
+
+### Primary Use Cases:
+1. **Brownfield Onboarding** - "What are this project's coding conventions?"
+2. **Standards Audit** - "Are we following our declared standards?"
+3. **New Contributor Onboarding** - "Teach me the project patterns"
+4. **Living Documentation** - "Keep standards in sync with codebase"
+5. **Greenfield Setup** - "Initialize standards from best practices"
+
+### Activation Triggers
+
+**Keywords**: analyze coding standards, discover conventions, code style, detect patterns, coding guidelines, what are the standards, naming conventions, best practices, code quality, standards audit, anti-patterns
+
+**User Requests**:
+- "What are the coding standards for this project?"
+- "Analyze the codebase and document our conventions"
+- "Check if we're following our declared standards"
+- "Find anti-patterns in the code"
+- "Generate coding standards documentation"
+- "What naming conventions does this project use?"
+
+---
+
+## Capabilities
+
+### 1. **Explicit Standards Discovery** (Fast - 5 seconds)
+- ✅ Detect existing `.specweave/docs/internal/governance/coding-standards.md`
+- ✅ Parse ESLint configuration (`.eslintrc.json`, `.eslintrc.js`)
+- ✅ Parse Prettier configuration (`.prettierrc`, `.prettierrc.json`)
+- ✅ Parse TypeScript configuration (`tsconfig.json`)
+- ✅ Parse EditorConfig (`.editorconfig`)
+- ✅ Extract standards from `CLAUDE.md`, `CONTRIBUTING.md`
+
+### 2. **Implicit Standards Detection** (Medium - 30 seconds)
+- ✅ Naming convention analysis (variables, functions, classes, constants)
+- ✅ Import pattern detection (extensions, ordering, aliasing)
+- ✅ Function characteristics (avg length, max length, arrow vs regular)
+- ✅ Type safety analysis (`any` usage, interface vs type preference)
+- ✅ Error handling patterns (try/catch usage, custom errors)
+- ✅ Comment style analysis
+- ✅ File organization patterns
+
+### 3. **Anti-Pattern Detection** (Fast - 15 seconds)
+- 🚨 `console.*` usage in production code
+- 🚨 Hardcoded secrets (API keys, passwords)
+- 🚨 `any` type overuse
+- 🚨 Large files (>500 lines)
+- 🚨 Long functions (>100 lines)
+- 🚨 Missing error handling
+- 🚨 N+1 query patterns
+- 🚨 Security vulnerabilities
+
+### 4. **Documentation Generation** (Fast - 10 seconds)
+- ✅ Generate standards document with examples
+- ✅ Include statistical confidence levels
+- ✅ Extract real code examples from codebase
+- ✅ Highlight inconsistencies and conflicts
+- ✅ Provide actionable recommendations
+- ✅ Link to violating files
+
+---
+
+## Analysis Process
+
+### Phase 1: Explicit Standards (5 seconds)
+
+**Sources Checked**:
+1. `.specweave/docs/internal/governance/coding-standards.md` (HIGH confidence)
+2. `CLAUDE.md` (HIGH confidence - AI instructions)
+3. `.eslintrc.json` (ENFORCED by tooling)
+4. `.prettierrc` (ENFORCED by tooling)
+5. `tsconfig.json` (ENFORCED by compiler)
+6. `.editorconfig` (ENFORCED by editor)
+7. `CONTRIBUTING.md` (MEDIUM confidence - may be outdated)
+
+**Output**:
+```markdown
+## Explicit Standards Found
+
+✅ .eslintrc.json (ENFORCED - ESLint active)
+✅ .prettierrc (ENFORCED - Prettier active)
+✅ tsconfig.json (ENFORCED - TypeScript compiler)
+✅ CLAUDE.md (HIGH - AI development rules)
+⚠️  CONTRIBUTING.md (MEDIUM - human guidelines)
+❌ No .specweave/docs/internal/governance/coding-standards.md
+```
+
+### Phase 2: Implicit Standards (30 seconds)
+
+**Analysis Performed**:
+- Scan `src/**/*.{ts,js,tsx,jsx}` files
+- Parse Abstract Syntax Trees (AST)
+- Calculate statistical patterns
+- Identify dominant conventions
+
+**Example Output**:
+```markdown
+## Detected Patterns
+
+### Naming Conventions (Confidence: 95%)
+- Variables: camelCase (1,234 samples, 98% compliance)
+- Functions: camelCase (567 samples, 100% compliance)
+- Classes: PascalCase (89 samples, 100% compliance)
+- Constants: UPPER_SNAKE_CASE (234 samples, 92% compliance)
+  ⚠️ 8% use camelCase (inconsistency detected)
+
+### Import Patterns (Confidence: 100%)
+- Extensions: .js suffix required (100% compliance)
+- Order: external → internal → types (87% compliance)
+
+### Function Characteristics
+- Average length: 35 lines
+- Max length: 156 lines (src/core/analyzer.ts:45)
+- Style: Arrow functions (78%), Regular (22%)
+
+### Type Safety (Confidence: 85%)
+- any usage: 12 instances (REVIEW NEEDED)
+- Preference: Interfaces (89%) over Types (11%)
+```
+
+### Phase 3: Anti-Pattern Detection (15 seconds)
+
+**Checks Performed**:
+- Security: Hardcoded secrets, SQL injection risks
+- Maintainability: Large files, complex functions
+- Performance: N+1 queries, missing caching
+- Robustness: Missing error handling
+
+**Example Output**:
+```markdown
+## Issues Found
+
+### 🔴 CRITICAL (2 issues)
+- Hardcoded Secrets: 2 instances
+  - src/config/api.ts:12
+  - src/utils/auth.ts:45
+  Fix: Use process.env variables
+
+### 🟠 HIGH (5 issues)
+- console.* Usage: 5 instances in src/
+  - src/core/analyzer.ts:67
+  Fix: Use logger abstraction
+
+### 🟡 MEDIUM (12 issues)
+- Large Files: 3 files > 500 lines
+  - src/core/orchestrator.ts (678 lines)
+  Fix: Split into modules
+```
+
+### Phase 4: Documentation Generation (10 seconds)
+
+**Merge Strategy**:
+1. Explicit standards = source of truth
+2. Implicit standards = fill gaps
+3. Anti-patterns = warnings + recommendations
+
+**Output**: `.specweave/docs/internal/governance/coding-standards-analysis.md`
+
+---
+
+## Integration Points
+
+### 1. Brownfield Analyzer Integration
+
+**Automatic**: Runs as part of brownfield analysis
+
+```
+User: "Analyze this brownfield project"
+
+Workflow:
+1. Scan project structure
+2. Classify documents
+3. Detect external tools
+4. → RUN code-standards-detective agent
+5. → GENERATE coding-standards.md
+6. Generate migration plan
+```
+
+### 2. Increment Planning
+
+**Reference**: Standards included in technical constraints
+
+```markdown
+## Technical Constraints
+
+Coding Standards: .specweave/docs/internal/governance/coding-standards.md
+- Naming: camelCase (vars), PascalCase (classes)
+- Functions: < 50 lines target
+- No console.* - use logger
+```
+
+### 3. Increment Completion
+
+**Optional**: Re-analyze on increment done
+
+```bash
+/specweave:done 0046 --update-standards
+```
+
+---
+
+## Usage Examples
+
+### Example 1: First-Time Analysis
+
+```
+User: "What are the coding standards for this project?"
+
+Skill: code-standards-analyzer
+
+Actions:
+1. Check for existing standards (none found)
+2. Parse .eslintrc.json, .prettierrc
+3. Analyze 1,234 TypeScript files
+4. Detect patterns with 95% confidence
+5. Generate standards document
+
+Output:
+"✅ Analysis complete! Generated coding standards at:
+.specweave/docs/internal/governance/coding-standards-analysis.md
+
+Key findings:
+- Naming: 98% camelCase compliance
+- Imports: 100% use .js extensions
+- Issues: 5 console.* usages, 2 hardcoded secrets
+- Recommendation: Formalize detected patterns as official standards"
+```
+
+### Example 2: Standards Audit
+
+```
+User: "Check if we're following our declared standards"
+
+Skill: code-standards-analyzer
+
+Actions:
+1. Read existing coding-standards.md
+2. Analyze current codebase
+3. Compare declared vs actual
+4. Report violations
+
+Output:
+"📊 Standards Compliance: 87%
+
+✅ Passing:
+- Naming conventions: 98% compliant
+- Import patterns: 100% compliant
+
+⚠️ Violations:
+- console.* usage: 12 instances (should be 0)
+- Large files: 3 files > 500 lines (should be 0)
+
+Recommendation: Fix violations or update standards to reflect reality"
+```
+
+### Example 3: New Contributor Onboarding
+
+```
+User: "I'm new to this codebase. What conventions should I follow?"
+
+Skill: code-standards-analyzer
+
+Actions:
+1. Load existing coding-standards.md
+2. Extract key rules with examples
+3. Highlight SpecWeave-specific patterns
+
+Output:
+"📚 Coding Standards Summary
+
+1. Naming:
+   - Variables: camelCase (e.g., `userId`, `isActive`)
+   - Functions: camelCase (e.g., `getUserById()`)
+   - Classes: PascalCase (e.g., `UserService`)
+
+2. Imports:
+   - Always use .js extensions
+   - Example: import { foo } from './bar.js'
+
+3. Error Handling:
+   - Use custom error types
+   - Example: throw new UserNotFoundError(id)
+
+4. Logging:
+   - NEVER use console.*
+   - Use logger abstraction instead
+
+Full standards: .specweave/docs/internal/governance/coding-standards.md"
+```
+
+---
+
+## Commands
+
+### Manual Analysis
+
+```bash
+# Full analysis
+/specweave:analyze-standards
+
+# Drift detection only
+/specweave:analyze-standards --drift
+
+# Update existing standards
+/specweave:analyze-standards --update
+```
+
+---
+
+## Output Files
+
+### 1. `coding-standards-analysis.md` (Auto-Generated)
+
+**Location**: `.specweave/docs/internal/governance/coding-standards-analysis.md`
+
+**Purpose**: Latest analysis report (gitignored, temporary)
+
+**Contents**:
+- Detected patterns with confidence levels
+- Real code examples
+- Statistical evidence
+- Violation warnings
+- Recommendations
+
+### 2. `coding-standards.md` (Source of Truth)
+
+**Location**: `.specweave/docs/internal/governance/coding-standards.md`
+
+**Purpose**: Official coding standards (git-tracked, manual + auto)
+
+**Contents**:
+- Naming conventions
+- Import patterns
+- Function guidelines
+- Type safety rules
+- Error handling
+- Security practices
+- Performance guidelines
+
+### 3. `coding-standards-history.md` (Change Log)
+
+**Location**: `.specweave/docs/internal/governance/coding-standards-history.md`
+
+**Purpose**: Track standard evolution over time
+
+**Contents**:
+- Timestamp of each analysis
+- Changes detected
+- Migration guides
+- Rationale for updates
+
+---
+
+## Best Practices
+
+### 1. Run During Onboarding
+- Analyze standards as part of brownfield analysis
+- Generate baseline documentation
+- Establish project context
+
+### 2. Periodic Re-Analysis
+- Quarterly reviews
+- After major refactors
+- On team onboarding
+
+### 3. Team Review Required
+- Don't auto-commit changes
+- Review generated standards
+- Discuss inconsistencies
+- Formalize decisions
+
+### 4. Living Documentation
+- Keep standards in sync with code
+- Update when patterns change
+- Track evolution in history
+
+### 5. Enforcement Through Tooling
+- Most standards → ESLint/Prettier
+- This skill → document what tools can't catch
+- Focus on SpecWeave-specific patterns
+
+---
+
+## Related Documentation
+
+- [Coding Standards](.specweave/docs/internal/governance/coding-standards.md) - Official standards
+- [Code Review Standards](.specweave/docs/internal/delivery/core/code-review-standards.md) - Review process
+- [Brownfield Analyzer](../brownfield-analyzer/SKILL.md) - Project analysis
+
+---
+
+## Technical Details
+
+### Supported Languages
+- ✅ TypeScript (primary)
+- ✅ JavaScript (ES6+)
+- 🔜 Python (future)
+- 🔜 Java (future)
+- 🔜 Go (future)
+
+### Detection Algorithms
+
+**Naming Convention Detection**:
+- Regex pattern matching
+- Statistical frequency analysis
+- AST node analysis
+- Confidence scoring (samples / total)
+
+**Anti-Pattern Detection**:
+- Static analysis (grep, AST parsing)
+- Rule-based checks
+- Security scanning
+- Complexity metrics
+
+**Confidence Levels**:
+- ENFORCED: Linter/compiler enforced (100%)
+- HIGH: 90%+ compliance in codebase
+- MEDIUM: 70-89% compliance
+- LOW: 50-69% compliance
+- CONFLICT: <50% compliance (inconsistent)
+
+---
+
+## Limitations
+
+1. **Implicit Standards**: Requires representative codebase sample
+2. **False Positives**: Anti-pattern detection may flag intentional code
+3. **Language Support**: Currently TypeScript/JavaScript only
+4. **Context**: Can't understand business rationale for patterns
+
+---
+
+## Future Enhancements
+
+- [ ] Multi-language support (Python, Java, Go)
+- [ ] Auto-generate ESLint rules from detected patterns
+- [ ] AI-powered suggestions from top OSS projects
+- [ ] Team-specific standards in multi-project mode
+- [ ] Pre-commit hook integration for enforcement
+- [ ] Real-time drift alerts
+- [ ] Standards comparison across projects