Code Health Remediation Framework

When This Activates

This skill activates when:

• Health scan shows issues to fix

• User wants to clean up codebase

• Removing dead code or duplicates

• Addressing tech debt

Health Score Interpretation

Score Rating Action

90-100 Excellent Maintain current practices

75-89 Good Address minor issues opportunistically

60-74 Fair Schedule cleanup sprint

40-59 Poor Prioritize remediation

0-39 Critical Immediate attention required

Issue Categories

1. Dead Code

Types:

• unused_export

• Exported but never imported elsewhere

• orphan_file

• File not imported by any other file

• unused_function

• Function defined but never called

Confidence Levels:

• High - Static analysis confirms no references

• Medium - May have dynamic references

• Low - Could be used via string import or reflection

2. Duplicates

Types:

• Exact duplicates (identical code blocks)

• Near duplicates (similar logic, different variables)

• Pattern duplicates (same structure, different implementations)

3. Security Issues

Types:

• Hardcoded secrets

• Unsafe eval/exec usage

• SQL injection vulnerabilities

• XSS vulnerabilities

4. Performance Issues

Types:

• N+1 queries

• Missing indexes

• Unbounded loops

• Memory leaks

Safe Remediation Workflow

Before Removing Dead Code

Verify with search

Check for string references

grep -r "functionName" .

Check for dynamic imports

grep -r "import(" .

Check test coverage

• Is the code tested directly?

• Is it a test helper?

Check for side effects

• Does it register listeners?

• Does it modify global state?

Review git history

• Why was it added?

• Was it recently used?

Removal Strategy

High confidence dead code:

1. Remove the code
2. Run tests
3. If tests pass, commit

Medium confidence:

1. Add deprecation comment
2. Log usage if called
3. Remove after verification period

Low confidence:

1. Don't remove automatically
2. Flag for manual review
3. Ask original author if available

Duplicate Consolidation

Steps

• Identify the canonical location

• Create shared utility if needed

• Update all callers to use shared version

• Remove duplicates

• Run tests

Example

// Before: duplicated in 3 files const formatDate = (d) => d.toISOString().split('T')[0];

// After: single location // utils/dates.ts export const formatDate = (d: Date) => d.toISOString().split('T')[0];

Health Config (Ignore Rules)

Projects can configure ignore rules in health_config.json :

{ "ignore": { "dead_code": [ {"file": "types.ts", "reason": "Type exports used via declaration merging"}, {"pattern": ".stories.tsx", "reason": "Storybook files"} ], "duplicates": [ {"pattern": ".test.ts", "reason": "Test setup can be duplicated"} ] }, "exclude_dirs": ["mocks", "fixtures"] }

MCP Tools for Health

Get current health status

memory_health action=status project=gyst

Trigger a new scan

memory_health action=scan project=gyst

Search for specific issues

memory_query "unused exports in auth"

Prioritization Matrix

Issue Type Impact Effort Priority

Security (hardcoded secrets) Critical Low P0

Large orphan files Medium Low P1

Duplicate logic Medium Medium P2

Unused exports Low Low P3

Minor duplicates Low Low P4

Remediation Report Template

Health Remediation Report

Project: [name] Score Before: [X]/100 Score After: [Y]/100

Removed

• [list of removed items]

Consolidated

• [list of deduplicated code]

Flagged for Review

• [items needing manual review]

Skipped (Configured Ignores)

• [items skipped per config]