Code Quality Verification

Purpose

Verify code for quality anti-patterns including poor naming, missing documentation, magic values, and organizational issues. All analysis happens locally.

When to Use

Trigger this skill when the user asks to:

• "verify agent quality"
• "verify quality"
• "check code quality"
• "review code organization"
• "check naming conventions"

Note: For full verification including security, patterns, and language-specific checks, tell the user to say "verify agent".

Process

Step 1: Discover Files

Locate files to analyze:

Source files:

• *.py, *.ts, *.js, *.go, *.rs - Source code
• Focus on main implementation files, not tests

Directories to check:

• src/, lib/, app/, project root
• agent/, tools/, utils/

Exclude:

• node_modules/, .venv/, venv/, __pycache__/
• Test files (*.test.*, *.spec.*, *_test.go)
• Generated files, migrations

Step 2: Run Quality Checks

All checks in this skill are [HEURISTIC] — they require judgment. Tag findings with [H].

---

2.1 [HEURISTIC] Naming Conventions

Check for:

Issue	Examples
Single-letter variables (except loops)	x = get_data(), d = {}
Unclear abbreviations	proc_usr_req(), calc_val()
Inconsistent casing	Mixing camelCase and snake_case in same file
Names that don't describe purpose	data, temp, result, info
Boolean names without is/has/can	enabled = check() vs is_enabled = check()

Good naming:

# ✅ Clear, descriptive
user_profile = get_user_profile(user_id)
is_authenticated = check_authentication(token)
max_retry_attempts = 3

# ⚠️ Unclear
x = get_up(uid)
auth = check(t)
n = 3

Severity: ⚠️ Warning

---

2.2 [HEURISTIC] Code Organization

Check for:

Issue	Description
Large files	> 500 lines for a single module
Large functions	> 50 lines for a single function
Deep nesting	> 4 levels of indentation
Mixed concerns	Business logic mixed with I/O in same function
God objects	Classes with > 10 public methods or > 20 attributes

Example issues:

# ⚠️ Warning - Deep nesting
def process(data):
    if condition1:
        if condition2:
            for item in items:
                if condition3:
                    if condition4:  # Too deep
                        ...

# ⚠️ Warning - Mixed concerns
def save_user(user):
    # Validation
    if not user.email:
        raise ValueError("...")
    # Business logic
    user.created_at = datetime.now()
    # Database I/O
    db.session.add(user)
    db.session.commit()
    # Email sending
    send_welcome_email(user)  # Multiple concerns

Severity: ⚠️ Warning

---

2.3 [HEURISTIC] Magic Numbers and Strings

Check for:

• Numeric literals in code without constants
• String literals repeated multiple times
• Configuration values hardcoded in logic

Examples:

# ⚠️ Warning - Magic numbers
if retry_count > 3:  # What does 3 mean?
    ...
time.sleep(60)  # Why 60?

# ⚠️ Warning - Repeated strings
if status == "pending":
    ...
elif status == "pending":  # Typo risk
    ...

# ✅ Good - Named constants
MAX_RETRIES = 3
RETRY_DELAY_SECONDS = 60
STATUS_PENDING = "pending"

if retry_count > MAX_RETRIES:
    ...
time.sleep(RETRY_DELAY_SECONDS)

Severity: ⚠️ Warning

---

2.4 [HEURISTIC] Documentation

Check for:

Missing	Where expected
Module docstring	Top of .py files
Class docstring	After class definition
Function docstring	After def for public functions
README	Project root
Type hints	Public function parameters/returns

Examples:

# ⚠️ Warning - Missing docstrings
def calculate_score(user, items, weights):
    total = 0
    for item, weight in zip(items, weights):
        total += item.value * weight
    return total

# ✅ Good - Documented
def calculate_score(user: User, items: list[Item], weights: list[float]) -> float:
    """
    Calculate weighted score for a user's items.
    
    Args:
        user: The user to calculate score for
        items: List of items to score
        weights: Weight multipliers for each item
        
    Returns:
        Total weighted score
    """
    ...

Severity: ⚠️ Warning

---

2.5 [HEURISTIC] Error Handling

Check for:

Issue	Description
Bare except	except: without specific exception
Silent failures	except: pass
Generic exceptions raised	raise Exception("...")
No error handling	Functions that can fail but don't handle errors

Examples:

# ⚠️ Warning - Bare except
try:
    process_data()
except:
    pass

# ⚠️ Warning - Generic exception
raise Exception("Something went wrong")

# ✅ Good - Specific handling
try:
    process_data()
except ValueError as e:
    logger.warning(f"Invalid data: {e}")
    return default_value
except ConnectionError as e:
    logger.error(f"Connection failed: {e}")
    raise ServiceUnavailableError from e

Severity: ⚠️ Warning

---

2.6 [HEURISTIC] Code Duplication

Check for:

• Identical or near-identical code blocks (> 5 lines)
• Copy-pasted functions with minor variations
• Repeated patterns that could be abstracted

Example:

# ⚠️ Warning - Duplication
def get_user_by_id(user_id):
    response = requests.get(f"{BASE_URL}/users/{user_id}")
    if response.status_code == 200:
        return response.json()
    return None

def get_order_by_id(order_id):
    response = requests.get(f"{BASE_URL}/orders/{order_id}")
    if response.status_code == 200:
        return response.json()
    return None

# ✅ Good - Abstracted
def get_resource(resource_type: str, resource_id: str):
    response = requests.get(f"{BASE_URL}/{resource_type}/{resource_id}")
    if response.status_code == 200:
        return response.json()
    return None

Severity: ⚠️ Warning

---

2.7 [HEURISTIC] Commented-Out Code

Check for:

• Large blocks of commented-out code (> 5 lines)
• TODO comments that are stale (months old if dates present)
• FIXME comments indicating known issues

Examples:

# ⚠️ Warning - Commented code should be removed
# def old_implementation():
#     for item in items:
#         process_item(item)
#     return results

# ⚠️ Warning - Stale TODO
# TODO: Fix this before launch (added 2024-01-15)

# ✅ Acceptable - Brief explanatory comment
# Note: Using legacy API format for backwards compatibility

Severity: ⚠️ Warning

---

Step 3: Generate Report

# Code Quality Verification Report

**Project:** [name or path]
**Date:** [current date]
**Files analyzed:** [count]

## Summary

✅ X checks passed | ⚠️ Y warnings | ❌ Z issues

## Naming

- [x] Naming conventions consistent
- [ ] ⚠️ Unclear names at `[file:line]`

## Organization

- [x] Code well-organized
- [ ] ⚠️ Large function at `[file:line]` ([X] lines)

## Documentation

- [x] Key functions documented
- [ ] ⚠️ Missing docstring at `[file:line]`

## Error Handling

- [x] Errors properly handled
- [ ] ⚠️ Bare except at `[file:line]`

## Findings

> `[H]` = heuristic (all quality checks require judgment)

### ✅ Passing
- `[H]` Consistent naming conventions throughout
- `[H]` Functions are well-scoped and focused

### ⚠️ Warnings
- `[H]` [Check]: [description]
  - **Location:** [file:line]
  - **Impact:** [why this matters]
  - **Suggestion:** [how to improve]

## Recommendations

1. [Priority recommendation]
2. [Additional improvements]

---

For full verification including security, patterns, and language-specific checks, say "verify agent".