tech-debt-remediation
Principal-engineer-level tech debt remediation with state tracking. Use when fixing violations properly, not just symptoms.
Packaged view
This page reorganizes the original catalog entry around fit, installability, and workflow context first. The original raw source lives below.
Install command
npx @skill-hub/cli install alicoding-nextura-tech-debt-remediation
Repository
Skill path: .claude/skills/tech-debt-remediation
Principal-engineer-level tech debt remediation with state tracking. Use when fixing violations properly, not just symptoms.
Open repositoryBest for
Primary workflow: Ship Full Stack.
Technical facets: Full Stack.
Target audience: everyone.
License: Unknown.
Original source
Catalog source: SkillHub Club.
Repository owner: alicoding.
This is still a mirrored public skill entry. Review the repository before installing into production workflows.
What it helps with
- Install tech-debt-remediation into Claude Code, Codex CLI, Gemini CLI, or OpenCode workflows
- Review https://github.com/alicoding/nextura before adding tech-debt-remediation to shared team environments
- Use tech-debt-remediation for development workflows
Works across
Favorites: 0.
Sub-skills: 0.
Aggregator: No.
Original source / Raw SKILL.md
---
name: tech-debt-remediation
scope: generic
description: >
Principal-engineer-level tech debt remediation with state tracking.
Use when fixing violations properly, not just symptoms.
version: 2.0.0
triggers:
- remediate tech debt
- fix violations
- principal engineer fix
- root cause fix
gates:
post:
- "pre-commit run --all-files"
- "pytest tests/ -q"
---
# Tech Debt Remediation
Fix violations at root cause, not symptoms. Principal-engineer quality.
---
## Quick Start
1. Load audit findings
2. Identify root cause (not symptom)
3. Plan fix with validation
4. Implement with tests
5. Verify pre-commit passes
---
## Root Cause vs Symptom
| Symptom | Root Cause | Fix |
|---------|------------|-----|
| Long function | Missing abstraction | Extract class/module |
| Duplicate code | No shared library | Create utility |
| Mixed concerns | Architecture violation | Separate layers |
| Missing tests | No TDD discipline | Add tests + process |
---
## Remediation State
Track in `data/.session/remediation-{id}/state.yaml`:
```yaml
task_id: REM-001
status: in_progress # pending | in_progress | blocked | complete
violations:
- id: V-001
type: size_limit
location: src/module.py
status: fixed
- id: V-002
type: missing_test
status: in_progress
validation:
pre_commit: pending
tests: pending
```
---
## STOP GATES
### STOP GATE 1: Audit Exists
**Check:** Is there an audit to remediate?
**Pass:** Audit findings loaded
**Fail:** STOP. Run codebase-audit first.
### STOP GATE 2: Root Cause Identified
**Check:** Is this fixing root cause, not symptom?
**Pass:** Root cause documented
**Fail:** STOP. Analyze deeper.
### STOP GATE 3: Pre-Commit Passes
**Check:** Do all hooks pass?
**Pass:** `pre-commit run --all-files` passes
**Fail:** STOP. Fix hook failures.
### STOP GATE 4: Tests Pass
**Check:** Do tests pass after fix?
**Pass:** `pytest tests/` passes
**Fail:** STOP. Fix test failures.
---
## Quick Reference
```
ORDER
1. Load audit
2. Identify root cause
3. Plan fix
4. Write test (TDD)
5. Implement fix
6. Run pre-commit
7. Run tests
8. Update state
NEVER
- Fix symptom only
- Skip pre-commit
- Skip tests
- Leave state incomplete
```
---
## Reference Files
- [reference/patterns.md](reference/patterns.md) - Remediation patterns
- [reference/state.md](reference/state.md) - State tracking schema