gh-tachyon-beep-skillpacks-plugins-axiom-system-architect/skills/using-system-architect/identifying-technical-debt.md

Identifying Technical Debt

Overview

Deliver first, explain after. Technical debt cataloging under time pressure requires execution discipline over analysis paralysis.

Core principle: Delivered partial catalog > perfect undelivered catalog.

When to Use

Use this skill when:

• Cataloging technical debt from architecture assessment
• Under time pressure with incomplete analysis
• Tempted to explain methodology instead of producing document
• Deciding between complete analysis (miss deadline) vs quick list (poor quality)
• Writing technical debt catalog document

The Fundamental Rule

Produce the document. Don't explain why you're producing it.

Stakeholders need deliverables, not methodology explanations.

Execution Discipline

The Iron Law

Time allocation priority:

1. Deliver (80% of time)
2. Decide (10% of time)
3. Explain (10% of time, after delivery)

NOT:

1. Explain (50% of time)
2. Analyze trade-offs (30% of time)
3. Deliver (20% of time, if at all)

Red Flag: Analysis Paralysis

If you catch yourself:

• Writing paragraphs about what you "would" do
• Explaining trade-offs before producing document
• Analyzing hypothetical scenarios
• Describing your methodology

STOP. Start writing the actual catalog.

Scoping Under Time Pressure

The Three Options Pattern

When time-constrained technical debt cataloging:

Option A: Complete analysis, miss deadline

• Choose when: Deadline is negotiable, completeness is critical
• Never choose when: Stakeholder has hard deadline for decisions

Option B: Partial analysis with limitations (RECOMMENDED)

• Document critical/high priority items fully
• Note medium/low items identified but not fully analyzed
• Explicit limitations section
• Delivery date for complete catalog
• Choose when: Stakeholder needs decision-making info on time

Option C: Quick list without proper analysis

• Choose when: Never. This damages credibility.
• Quick lists without effort estimates are guesses, not analysis

Professional Partial Delivery

Partial catalog structure:

# Technical Debt Catalog (PARTIAL ANALYSIS)

**Coverage:** [X of Y items analyzed]
**Priority Focus:** Critical + High priority items
**Status:** [Z] medium/low priority items identified, detailed analysis pending
**Complete Catalog Delivery:** [Date]
**Confidence:** HIGH for items below, MEDIUM for pending analysis

## Critical Priority (Immediate Action Required)

### [Item Name]
**Evidence:** `path/to/file.py`, `path/to/other.js`
**Impact:** [Business + Technical consequences]
**Effort:** [S/M/L/XL or days]
**Category:** Security / Architecture / Code Quality / Performance
**Details:** [Specific description with examples]

[Repeat for all critical items]

## High Priority (Next Quarter)

[Same structure for high priority items]

## Pending Analysis

**Medium Priority:** [X items identified]
- [Item name]: [1-sentence description]
- [Item name]: [1-sentence description]

**Low Priority:** [Y items identified]
- [Listed but not analyzed]

## Limitations

This catalog analyzes [X] of [Y] identified technical debt items, focusing on Critical and High priority issues requiring immediate business decisions.

**Not included in this analysis:**
- Detailed effort estimates for medium/low items
- Code complexity metrics
- Dependency vulnerability scan
- Performance profiling results

**Complete catalog delivery:** [Date - typically 3-5 days after initial]

**Confidence:** No additional Critical priority items expected based on codebase review patterns.

Catalog Entry Requirements

Minimum Viable Entry (Time-Constrained)

Every cataloged item MUST have:

• Name - Clear, specific title
• Evidence - At least 1 file path showing the issue
• Impact - 1 sentence business + technical consequence
• Effort - T-shirt size (S/M/L/XL) or day estimate
• Category - Security, Architecture, Code Quality, or Performance

Time per entry: 3-5 minutes for minimum viable

Enhanced Entry (If Time Allows)

Nice-to-have additions:

• Multiple evidence citations
• Code examples showing the problem
• Specific recommendations
• Dependencies between debt items
• ROI calculations

Time per entry: 10-15 minutes for enhanced

Under time pressure: Minimum for ALL critical/high > Enhanced for SOME

Time-Boxing Pattern

For 90-minute deadline with 40+ items identified:

Time	Activity	Output
0-5 min	Decide scope (A/B/C)	Option B: Critical + High
5-15 min	Document structure	Template with sections
15-75 min	Catalog items	10-12 critical/high items @ 5 min each
75-85 min	Limitations section	Explicit scope, pending items
85-90 min	Executive summary	Stakeholder-ready intro

Total: 90 minutes, deliverable complete

NOT:

• 0-20 min: Explain reasoning
• 20-30 min: Hypothetical scenarios
• 30-90 min: Incomplete document or nothing

Prioritization for Scoping

Under time pressure, priority order:

1. Critical - Security vulnerabilities, data loss risks, system failure
2. High - Business growth constrained, architectural problems, zero tests
3. Medium - Performance issues, maintainability, code quality
4. Low - Code formatting, documentation gaps, minor optimizations

If you can only catalog 10 items, catalog the 10 highest priority items properly.

Don't catalog 40 items poorly.

Common Mistakes

Mistake	Why It's Wrong	Fix
Explaining instead of delivering	Wastes execution time	Write document first, explain if asked
Incomplete entries "to save time"	Damages credibility, unusable for decisions	Minimum viable entry for all cataloged items
Cataloging everything shallowly	False completeness, no decision value	Catalog fewer items deeply
No limitations section	Stakeholder thinks analysis is complete	Explicit scope and pending items
Missing delivery date	Open-ended, no accountability	Specific date for complete catalog

Handling Time Pressure

Economic Pressure (Stakeholder Meeting)

Situation: "Presentation in 90 minutes, need catalog"

Rationalization: "Better to list everything quickly than deep-dive on a few"

Reality: Stakeholder needs actionable information, not inventory lists.

Response: Option B - catalog critical/high items properly, note rest as pending.

Exhaustion Pressure

Situation: "I've been analyzing for 6 hours, I'm exhausted"

Rationalization: "Just explain what I found, write document later"

Reality: Later = never when deadline is now.

Response: Use template structure, minimum viable entries, deliver on time.

Perfectionism Pressure

Situation: "Partial catalog isn't professional"

Rationalization: "All or nothing, complete catalog or reschedule"

Reality: Partial professional analysis > complete amateur list > nothing.

Response: Deliver partial catalog with explicit limitations. This IS professional.

Professional Partial Catalogs

Partial catalog is professional when:

• Explicit about scope (X of Y analyzed)
• Focused on highest priority items
• Proper analysis depth for cataloged items
• Clear limitations section
• Delivery date for complete analysis
• Confidence statement about uncatalogued items

Partial catalog is unprofessional when:

• Pretends to be complete
• Shallow analysis of everything
• No indication of what's missing
• No delivery date for full catalog
• Unclear priorities

Evidence Requirements

Every technical debt item needs evidence.

❌ Bad:

### Authentication Issues
The auth system has problems.
**Effort:** Large

✅ Good (Minimum):

### Weak Password Hashing (MD5)
**Evidence:** `src/auth/password.py:23` - uses MD5, should be bcrypt
**Impact:** Password database breach exposes user passwords immediately
**Effort:** M (2-3 days to migrate + test)
**Category:** Security

✅ Better (If Time):

### Weak Password Hashing (MD5)
**Evidence:**
- `src/auth/password.py:23-45` - MD5 hashing implementation
- `tests/test_auth.py` - no password security tests
- 45,000 user accounts in production database

**Impact:**
- Business: Regulatory violation (GDPR, SOC2), breach notification required
- Technical: Cannot rotate hashing algorithm without full user password reset
- Security: MD5 rainbow tables enable instant password recovery from breach

**Effort:** M (2-3 days)
- Implement bcrypt wrapper (4 hours)
- Add backward compatibility for MD5 (2 hours)
- Migrate users on login (passive, 2-3 months)
- Add security tests (4 hours)

**Category:** Security (Critical)

**Recommendation:** Immediate replacement with bcrypt + gradual migration strategy

Under time pressure: First example (minimum). Second example only if time allows.

Red Flags - STOP

If you're doing any of these:

• "Let me explain my reasoning for choosing Option B..."
• "With more time I would..."
• "The trade-offs are..."
• "This approach balances..."
• Writing > 2 paragraphs before starting actual catalog

All of these mean: You're explaining instead of delivering. Stop. Start cataloging.

Rationalization Table

Excuse	Reality
"Stakeholder needs my reasoning"	Stakeholder needs the catalog. Reasoning can come after.
"Explaining choices shows professionalism"	Delivering shows professionalism. Explaining without delivering shows analysis paralysis.
"Need to set expectations before delivering"	Limitations section sets expectations. Write it in the document.
"Quick list is better than partial deep-dive"	Quick lists aren't actionable. Partial proper analysis is.
"I should explain trade-offs"	Document structure explains itself. Deliver it.
"Perfect is enemy of good"	Correct! So deliver the "good" (partial catalog). Don't just explain this principle.

The Bottom Line

Under time pressure:

1. Decide quickly (5 minutes) - Option A, B, or C
2. Execute immediately (80% of remaining time) - Write the document
3. Deliver on time (Not negotiable) - Stakeholder gets deliverable
4. Explain if asked (After delivery) - Methodology comes second

Delivered partial analysis beats perfect undelivered analysis every time.

Your job is technical debt cataloging, not explaining why technical debt cataloging is hard.

Catalog the debt. Deliver the document. Explanation is optional.

Real-World Impact

From baseline testing (2025-11-13):

• Scenario 2: Agent without this skill explained methodology for 20 minutes, delivered nothing
• Agent chose correct option (B - partial with limitations) but failed to execute
• With this skill: Agent must deliver document first, explanation after
• Key shift: Execution over analysis, delivery over methodology