🔎 ln-341-code-quality-checker Workflow

Linear Workflow - Worker v1.0.0

Overview

Purpose: Analyze code quality of Done implementation tasks for DRY/KISS/YAGNI/Architecture violations and guide compliance.

Type: Linear Workflow (5 sequential phases)

Single Responsibility: ONLY analyzes code quality and reports issues - does NOT create tasks or change statuses.

Fail Fast: Phase 4 Step 1 in ln-330-story-executor - checks quality BEFORE testing to catch refactoring needs early.

graph TD Start([START]) --> Phase1[Phase 1: Discovery
Load Story
Discover guides
Extract guide links] Phase1 --> Phase2[Phase 2: Load Done Tasks
Query implementation tasks
Filter out test tasks
Identify affected files] Phase2 --> Phase3[Phase 3: Analyze Changes
Extract git diffs
Read file contents
Parse AST] Phase3 --> Phase4[Phase 4: Check Violations
Check 1: DRY duplicates
Check 2: KISS complexity
Check 3: YAGNI unused
Check 4: Architecture layers
Check 5: Guide compliance] Phase4 --> Phase5[Phase 5: Report Results
Categorize by severity
Linear comment
Return JSON verdict] Phase5 --> End([END:
JSON verdict + issues]) classDef phase fill:#E3F2FD,stroke:#1976D2,stroke-width:2px classDef endpoint fill:#C8E6C9,stroke:#388E3C,stroke-width:2px class Phase1,Phase2,Phase3,Phase4,Phase5 phase class Start,End endpoint

Phase Descriptions

Phase 1: Discovery

Load Story from Linear via MCP
Extract Story.id (UUID) for parentId filter
Discover available guides in docs/guides/
Parse Story Technical Notes for guide links

Phase 2: Load Done Implementation Tasks

Query Linear for Story's child tasks with state="Done"
Filter OUT test tasks (label "tests" or title contains "test")
Extract affected files from task "Affected Components" section

Phase 3: Analyze Code Changes

Extract git diffs for each task (git diff main...[branch])
Read file contents via Read tool
Parse AST (Abstract Syntax Tree) for code structure
Identify functions, classes, imports, complexity metrics

Phase 4: Check Violations (5 checks)

Check 1: DRY - Duplicate code blocks, functions, validation logic
Check 2: KISS - High cyclomatic complexity (>10), deep nesting, long functions
Check 3: YAGNI - Unused code, premature abstraction, over-engineering
Check 4: Architecture - Layer violations, circular dependencies, domain logic in wrong layer
Check 5: Guide Compliance - Code doesn't follow recommended patterns from guides

Phase 5: Report Results

Categorize issues by severity (HIGH/MEDIUM/LOW)
Determine verdict (PASS if no HIGH/MEDIUM issues)
Format Linear comment with categorized issues
Add comment to Story
Return JSON verdict with detailed issue list

Violation Types

1. DRY (Don't Repeat Yourself)

Detects: Duplicate functions, code blocks, validation logic, error handling patterns

Example: Same validation function in 3 different files

Fix: Extract to shared utility module

Severity: HIGH if >2 duplicates, MEDIUM if 2 duplicates

2. KISS (Keep It Simple)

Detects: High cyclomatic complexity (>10), deep nesting (>4 levels), long functions (>50 lines)

Example: Function with 5 nested if statements

Fix: Simplify with early returns, extract helper functions

Severity: HIGH if complexity >15, MEDIUM if >10

3. YAGNI (You Aren't Gonna Need It)

Detects: Unused functions, premature abstraction, over-engineering

Example: Interface with only one implementation

Fix: Remove unused code, simplify abstraction

Severity: MEDIUM (doesn't break functionality, adds maintenance burden)

4. Architecture Violations

Detects: Layer violations (controller → repository, skipping service), circular dependencies

Example: Controller imports Repository directly instead of Service

Fix: Follow layer hierarchy: Controller → Service → Repository

Severity: HIGH (breaks architecture, creates coupling)

5. Guide Compliance Violations

Detects: Code doesn't follow recommended patterns from project guides

Example: Custom JWT implementation instead of authlib (Guide 01 recommendation)

Fix: Use recommended library/pattern from guide

Severity: HIGH if security/critical, MEDIUM otherwise

Output Format

{
  "verdict": "PASS" | "ISSUES_FOUND",
  "story_id": "US001",
  "tasks_analyzed": 3,
  "issues": [
    {
      "type": "DRY",
      "severity": "HIGH",
      "file": "src/auth/service.py",
      "line": 42,
      "description": "Duplicate validation logic in 3 places",
      "suggestion": "Extract to shared validator function"
    }
  ],
  "summary": {
    "dry_violations": 2,
    "kiss_violations": 1,
    "yagni_violations": 0,
    "architecture_violations": 1,
    "guide_violations": 1,
    "total_issues": 5,
    "high_severity": 3,
    "medium_severity": 2,
    "low_severity": 0
  },
  "linear_comment_id": "abc123"
}

Key Characteristics

Atomic Worker: Single responsibility - code analysis only
Fail Fast: Runs FIRST in Phase 4 (before testing) to catch refactoring needs early
AST-Based: Uses Abstract Syntax Tree parsing for accurate code analysis
Multi-Dimensional: Checks 5 violation types (DRY/KISS/YAGNI/Architecture/Guide Compliance)
Severity Categorization: Issues ranked HIGH/MEDIUM/LOW for prioritization
Guide Integration: Validates code follows project-specific patterns

Complexity Metrics

Cyclomatic Complexity Thresholds:

1-5: Simple, low risk
6-10: Moderate complexity
11-15: Complex, needs refactoring (MEDIUM severity)
16+: Very complex, high risk (HIGH severity)