gh-tachyon-beep-skillpacks-plugins-axiom-system-archaeologist/skills/using-system-archaeologist/.archive/untested/assessing-code-quality-v1-untested.md

Assessing Code Quality

Purpose

Analyze code quality indicators beyond architecture to identify maintainability issues, code smells, and technical debt - produces quality scorecard with actionable improvement recommendations.

When to Use

• Coordinator delegates quality assessment after subsystem catalog completion
• Task specifies analyzing code quality in addition to architecture
• Need to identify refactoring priorities beyond structural concerns
• Output feeds into architect handover reports or improvement planning

Core Principle: Evidence-Based Quality Assessment

Good quality analysis identifies specific, actionable issues. Poor quality analysis makes vague claims about "bad code."

Your goal: Provide evidence-based quality metrics with concrete examples and remediation guidance.

Quality Analysis Dimensions

1. Code Complexity

What to assess:

• Function/method length (lines of code)
• Cyclomatic complexity (decision points)
• Nesting depth (indentation levels)
• Parameter count

Evidence to collect:

• Longest functions with line counts
• Functions with highest decision complexity
• Deeply nested structures (> 4 levels)
• Functions with >5 parameters

Thresholds (guidelines, not rules):

• Functions > 50 lines: Flag for review
• Cyclomatic complexity > 10: Consider refactoring
• Nesting > 4 levels: Simplification candidate
• Parameters > 5: Consider parameter object

Example documentation:

### Complexity Concerns

**High complexity functions:**
- `src/api/order_processing.py:process_order()` - 127 lines, complexity ~15
  - 8 nested if statements
  - Handles validation, pricing, inventory, shipping in single function
  - **Recommendation:** Extract validation, pricing, inventory, shipping into separate functions

- `src/utils/data_transform.py:transform_dataset()` - 89 lines, 7 parameters
  - **Recommendation:** Create DatasetConfig object to replace parameter list

2. Code Duplication

What to assess:

• Repeated code blocks (copy-paste patterns)
• Similar functions with slight variations
• Duplicated logic across subsystems

Evidence to collect:

• Quote repeated code blocks (5+ lines)
• List functions with similar structure
• Note duplication percentage (if tool available)

Analysis approach:

1. Read representative files from each subsystem
2. Look for similar patterns, function structures
3. Note copy-paste indicators (similar variable names, comment duplication)
4. Assess if duplication is deliberate or accidental

Example documentation:

### Duplication Concerns

**Copy-paste pattern in validation:**
- `src/api/users.py:validate_user()` (lines 45-67)
- `src/api/orders.py:validate_order()` (lines 89-111)
- `src/api/products.py:validate_product()` (lines 23-45)

All three functions follow identical structure:
1. Check required fields
2. Validate format with regex
3. Check database constraints
4. Return validation result

**Recommendation:** Extract common validation framework to `src/utils/validation.py`

3. Code Smells

Common smells to identify:

Long parameter lists:

• Functions with >5 parameters
• Recommendation: Parameter object or builder pattern

God objects/functions:

• Classes with >10 methods
• Functions doing multiple unrelated things
• Recommendation: Single Responsibility Principle refactoring

Magic numbers:

• Hardcoded values without named constants
• Recommendation: Extract to configuration or named constants

Dead code:

• Commented-out code blocks
• Unused functions/classes (no references found)
• Recommendation: Remove or document why kept

Shotgun surgery indicators:

• Single feature change requires edits in 5+ files
• Indicates high coupling
• Recommendation: Improve encapsulation

Example documentation:

### Code Smell Observations

**Magic numbers:**
- `src/services/cache.py`: Hardcoded timeout values (300, 3600, 86400)
  - **Recommendation:** Extract to CacheConfig with named durations

**Dead code:**
- `src/legacy/` directory contains 15 files, no imports found in active code
  - Last modified: 2023-06-15
  - **Recommendation:** Archive or remove if truly unused

**Shotgun surgery:**
- Adding new payment method requires changes in:
  - `src/api/payment.py`
  - `src/models/transaction.py`
  - `src/utils/validators.py`
  - `src/services/notification.py`
  - `config/payment_providers.json`
  - **Recommendation:** Introduce payment provider abstraction layer

4. Maintainability Indicators

What to assess:

• Documentation coverage (docstrings, comments)
• Test coverage (if test files visible)
• Error handling patterns
• Logging consistency

Evidence to collect:

• Percentage of functions with docstrings
• Test file presence per module
• Error handling approaches (try/except, error codes, etc.)
• Logging statements (presence, consistency)

Example documentation:

### Maintainability Assessment

**Documentation:**
- 12/45 functions (27%) have docstrings
- Public API modules better documented than internal utilities
- **Recommendation:** Add docstrings to all public functions, focus on "why" not "what"

**Error handling inconsistency:**
- `src/api/` uses exception raising
- `src/services/` uses error code returns
- `src/utils/` mixes both approaches
- **Recommendation:** Standardize on exceptions with custom exception hierarchy

**Logging:**
- Inconsistent log levels (some files use DEBUG for errors)
- No structured logging (difficult to parse)
- **Recommendation:** Adopt structured logging library, establish level conventions

5. Dependency Quality

What to assess:

• Coupling between subsystems
• Circular dependencies
• External dependency management

Evidence from subsystem catalog:

• Review "Dependencies - Outbound" sections
• Count dependencies per subsystem
• Identify bidirectional dependencies (A→B and B→A)

Analysis approach:

1. Use subsystem catalog dependency data
2. Count inbound/outbound dependencies per subsystem
3. Identify highly coupled subsystems (>5 dependencies)
4. Note circular dependency patterns

Example documentation:

### Dependency Concerns

**High coupling:**
- `API Gateway` subsystem: 8 outbound dependencies (most in system)
  - Depends on: Auth, User, Product, Order, Payment, Notification, Logging, Cache
  - **Observation:** Acts as orchestrator, coupling may be appropriate
  - **Recommendation:** Monitor for API Gateway becoming bloated

**Circular dependencies:**
- `User Service` ↔ `Notification Service`
  - User triggers notifications, Notification updates user preferences
  - **Recommendation:** Introduce event bus to break circular dependency

**Dependency concentration:**
- 6/10 subsystems depend on `Database Layer`
- Database Layer has no abstraction (direct SQL queries)
- **Recommendation:** Consider repository pattern to isolate database logic

Output Contract

Write findings to workspace as 05-quality-assessment.md:

# Code Quality Assessment

**Analysis Date:** YYYY-MM-DD
**Scope:** [Subsystems analyzed]
**Methodology:** Static code review, pattern analysis

## Quality Scorecard

| Dimension | Rating | Severity | Evidence Count |
|-----------|--------|----------|----------------|
| Complexity | Medium | 3 High, 5 Medium | 8 functions flagged |
| Duplication | High | 2 Critical, 4 Medium | 6 patterns identified |
| Code Smells | Medium | 0 Critical, 7 Medium | 7 smells documented |
| Maintainability | Medium-Low | 1 Critical, 3 Medium | 4 concerns noted |
| Dependencies | Low | 1 Medium | 2 concerns noted |

**Overall Rating:** Medium - Several actionable improvements identified, no critical blockers

## Detailed Findings

### 1. Complexity Concerns

[List from analysis above]

### 2. Duplication Concerns

[List from analysis above]

### 3. Code Smell Observations

[List from analysis above]

### 4. Maintainability Assessment

[List from analysis above]

### 5. Dependency Concerns

[List from analysis above]

## Prioritized Recommendations

### Critical (Address Immediately)
1. [Issue with highest impact]

### High (Next Sprint)
2. [Important issues]
3. [Important issues]

### Medium (Next Quarter)
4. [Moderate issues]
5. [Moderate issues]

### Low (Backlog)
6. [Nice-to-have improvements]

## Methodology Notes

**Analysis approach:**
- Sampled [N] representative files across [M] subsystems
- Focused on [specific areas of concern]
- Did NOT use automated tools (manual review only)

**Limitations:**
- Sample-based (not exhaustive)
- No runtime analysis (static review only)
- Test coverage estimates based on file presence
- No quantitative complexity metrics (manual assessment)

**For comprehensive analysis, consider:**
- Running static analysis tools (ruff, pylint, mypy for Python)
- Measuring actual test coverage
- Profiling runtime behavior
- Security-focused code review

Severity Rating Guidelines

Critical:

• Blocks core functionality or deployment
• Security vulnerability present
• Data corruption risk
• Examples: SQL injection, hardcoded credentials, unhandled exceptions in critical path

High:

• Significant maintainability impact
• High effort to modify or extend
• Frequent source of bugs
• Examples: God objects, extreme duplication, shotgun surgery patterns

Medium:

• Moderate maintainability concern
• Refactoring beneficial but not urgent
• Examples: Long functions, missing documentation, inconsistent error handling

Low:

• Minor quality improvement
• Cosmetic or style issues
• Examples: Magic numbers, verbose naming, minor duplication

Integration with Architect Handover

Quality assessment feeds directly into creating-architect-handover.md:

1. Quality scorecard provides severity ratings
2. Prioritized recommendations become architect's action items
3. Code smells inform refactoring strategy
4. Dependency concerns guide architectural improvements

The architect handover briefing will synthesize architecture + quality into comprehensive improvement plan.

When to Skip Quality Assessment

Optional scenarios:

• User requested architecture-only analysis
• Extremely tight time constraints (< 2 hours total)
• Codebase is very small (< 1000 lines)
• Quality issues not relevant to stakeholder needs

Document if skipped:

## Quality Assessment: SKIPPED

**Reason:** [Time constraints / Not requested / etc.]
**Recommendation:** Run focused quality review post-stakeholder presentation

Systematic Analysis Checklist

[ ] Read subsystem catalog to understand structure
[ ] Sample 3-5 representative files per subsystem
[ ] Document complexity concerns (functions >50 lines, high nesting)
[ ] Identify duplication patterns (repeated code blocks)
[ ] Note code smells (god objects, magic numbers, dead code)
[ ] Assess maintainability (docs, tests, error handling)
[ ] Review dependencies from catalog (coupling, circular deps)
[ ] Rate severity for each finding (Critical/High/Medium/Low)
[ ] Prioritize recommendations by impact
[ ] Write to 05-quality-assessment.md following contract
[ ] Document methodology and limitations

Success Criteria

You succeeded when:

• Quality assessment covers all 5 dimensions
• Each finding has concrete evidence (file paths, line numbers, examples)
• Severity ratings are justified
• Recommendations are specific and actionable
• Methodology and limitations documented
• Output written to 05-quality-assessment.md

You failed when:

• Vague claims without evidence ("code is messy")
• No severity ratings or priorities
• Recommendations are generic ("improve code quality")
• Missing methodology notes
• Skipped dimensions without documentation

Common Mistakes

❌ Analysis paralysis "Need to read every file" → Sample strategically, 20% coverage reveals patterns

❌ Vague findings "Functions are too complex" → "process_order() is 127 lines with complexity ~15"

❌ No prioritization Flat list of 50 issues → Prioritize by severity/impact, focus on Critical/High

❌ Tool-dependent "Can't assess without linting tools" → Manual review reveals patterns, note as limitation

❌ Perfectionism "Everything needs fixing" → Focus on high-impact issues, accept some technical debt

Integration with Workflow

This briefing is typically invoked as:

1. Coordinator completes subsystem catalog (02-subsystem-catalog.md)
2. Coordinator (optionally) validates catalog
3. Coordinator writes task specification for quality assessment
4. YOU read subsystem catalog to understand structure
5. YOU perform systematic quality analysis (5 dimensions)
6. YOU write to 05-quality-assessment.md following contract
7. Coordinator proceeds to diagram generation or architect handover

Your role: Complement architectural analysis with code quality insights, providing evidence-based improvement recommendations.