القائمة
Detects and quantifies technical, knowledge, architecture, documentation, and testing debt; rates severity and produces a prioritized paydown plan in time/risk/money terms.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Communicate efficiently without sacrificing clarity - natural, concise, actionable. Global skill loaded for every command and agent.
Use when reviewing or building UI components - ensures keyboard, screen-reader, and visual accessibility (WCAG 2.1 AA) so a11y is built in, not retrofitted.
You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation.
Manages context caching to optimize token usage and cost by creating, incrementally updating, and invalidating caches while verifying integrity before reuse.
Clean code and engineering discipline: modularity, readability, sizing, naming, duplication, separation of concerns, plus the four behavioral principles - think before coding, simplicity first, surgical changes, and goal-driven execution. Global skill applied to all coding work.
Detects and resolves drift between code, documentation, and contextual knowledge, classifying each drift and recommending concrete sync actions to keep artifacts consistent.
| name | debt-detection |
| description | Detects and quantifies technical, knowledge, architecture, documentation, and testing debt; rates severity and produces a prioritized paydown plan in time/risk/money terms. |
| auto_load | ["audit","refactor","sync"] |
| applies_to | ["architect","reviewer","backend","frontend"] |
Identify and quantify technical debt, knowledge debt, architecture debt, documentation debt, and testing debt across the codebase to prioritize remediation efforts.
The debt-detection skill systematically analyzes the codebase for various forms of debt that slow development, increase maintenance costs, or raise risks. It categorizes debt by type, severity, and remediation cost to enable informed decisions about debt paydown versus new feature development.
Task: Analyze codebase for technical debt
Input: src/ directory (45,000 lines)
Output:
Findings:
- 15 classes exceed 500 lines (largest: 1,200 lines)
- Cyclomatic complexity >15 in 23 functions
- Duplicated code: 8 instances of similar API calling logic
- 47 TODO comments, 12 are >6 months old
- Error handling inconsistent across 30% of modules
Debt type: Technical
Severity: High
Impact: New features take 30% longer, bugs in duplicated logic
Effort: 3-4 weeks to remediate primary issues
Recommended action:
1. Extract common API logic to shared service (1 week)
2. Refactor 5 largest classes (2 weeks)
3. Standardize error handling (1 week)
4. Address critical TODOs (ongoing)
Risks: Accumulating complexity, harder onboarding, more bugs
Files affected: src/services/*.ts, src/utils/api.ts (new)
Task: Identify knowledge gaps and undocumented decisions
Input: Project codebase and documentation
Output:
Findings:
- No architectural decision records (ADRs)
- Critical business logic in src/billing/* lacks comments
- 3 key algorithms without explanation (tax calc, pricing, discounts)
- Team turnover: 2 original developers left, knowledge lost
- No onboarding guide for new developers
Debt type: Knowledge
Severity: Critical
Impact: Bus factor = 1 for billing system, slow onboarding
Effort: 2 weeks to document critical paths
Recommended action:
1. Create ADRs for 5 major decisions (3 days)
2. Document billing logic with examples (1 week)
3. Write onboarding guide (3 days)
4. Record video walkthrough of architecture (1 day)
Risks: Project stalls if key person leaves, repeated mistakes
Files affected: docs/adr/*.md (new), docs/ONBOARDING.md (new), src/billing/* (comments)
Task: Evaluate architectural consistency and scalability
Input: src/ architecture, docs/architecture/
Output:
Findings:
- Circular dependencies between 4 modules
- Tight coupling: Auth module directly calls 8 other modules
- No service layer, controllers call database directly
- Monolithic deployment but documentation describes microservices
- Global state used for caching (not horizontally scalable)
Debt type: Architecture
Severity: High
Impact: Cannot scale horizontally, hard to test, fragile changes
Effort: 8-12 weeks major refactoring
Recommended action:
1. Break circular dependencies (2 weeks)
2. Introduce service layer (4 weeks)
3. Implement proper dependency injection (2 weeks)
4. Replace global state with distributed cache (2 weeks)
5. Update architecture docs to match reality (1 week)
Risks: System cannot scale with user growth, outages likely
Files affected: src/**/*.ts (architectural changes across codebase)
Task: Audit documentation completeness and accuracy
Input: docs/, README.md, inline comments
Output:
Findings:
- API documentation 40% complete (15 of 38 endpoints)
- README installation steps outdated (references old tool versions)
- 8 public functions lack JSDoc comments
- No contributing guidelines
- Inline comments <10% of codebase (industry avg 20-30%)
Debt type: Documentation
Severity: Medium
Impact: Hard for external contributors, slow onboarding, support load
Effort: 2-3 weeks
Recommended action:
1. Complete API documentation (1 week)
2. Update README with current setup (1 day)
3. Add JSDoc to public APIs (3 days)
4. Write CONTRIBUTING.md (2 days)
5. Add inline comments to complex logic (ongoing)
Risks: Frustrated users, wrong assumptions, repeated questions
Files affected: docs/api/*.md, README.md, CONTRIBUTING.md (new), src/**/*.ts
Task: Analyze test coverage and quality
Input: Test files, coverage reports
Output:
Findings:
- Overall coverage: 45% (target: 80%)
- 0% coverage in src/payments/ (critical path!)
- No integration tests for API endpoints
- 15 test files have only happy-path tests
- E2E tests disabled due to flakiness (6 months ago)
- Average test age: 8 months (code changes faster than tests)
Debt type: Testing
Severity: Critical
Impact: Bugs in production, fear of refactoring, slow releases
Effort: 4-6 weeks
Recommended action:
1. Add tests for payment module (1 week, highest priority)
2. Implement integration tests (2 weeks)
3. Add error case tests (1 week)
4. Fix and re-enable E2E tests (1 week)
5. Establish test-first culture (ongoing)
Risks: Production incidents, customer data issues, regulatory problems
Files affected: tests/**/*.test.ts (new and updated)