Initial commit

skills/using-system-architect/SKILL.md

@@ -0,0 +1,359 @@
+---
+name: using-system-architect
+description: Use when you have architecture documentation from system-archaeologist and need critical assessment, refactoring recommendations, or improvement prioritization - routes to appropriate architect specialist skills
+---
+
+# Using System Architect
+
+## Overview
+
+**System Architect provides critical assessment and strategic recommendations for existing codebases.**
+
+The architect works WITH the archaeologist: archaeologist documents what exists (neutral), architect assesses quality and recommends improvements (critical).
+
+## When to Use
+
+Use system-architect skills when:
+- You have archaeologist outputs (subsystem catalog, diagrams, architecture report)
+- Need to assess architectural quality ("how bad is it?")
+- Need to identify and catalog technical debt
+- Need refactoring strategy recommendations
+- Need to prioritize improvements with limited resources
+- User asks: "What should I fix first?" or "Is this architecture good?"
+
+## The Pipeline
+
+```
+Archaeologist → Architect → (Future: Project Manager)
+(documents)     (assesses)    (manages execution)
+```
+
+**Archaeologist** (axiom-system-archaeologist):
+- Neutral documentation of existing architecture
+- Subsystem catalog, C4 diagrams, dependency mapping
+- "Here's what you have"
+
+**Architect** (axiom-system-architect - this plugin):
+- Critical assessment of quality
+- Technical debt cataloging
+- Refactoring recommendations
+- Priority-based roadmaps
+- "Here's what's wrong and how to fix it"
+
+**Project Manager** (future: axiom-project-manager):
+- Execution tracking
+- Sprint planning
+- Risk management
+- "Here's how we'll track the fixes"
+
+## Available Architect Skills
+
+### 1. assessing-architecture-quality
+
+**Use when:**
+- Writing architecture quality assessment
+- Feel pressure to soften critique or lead with strengths
+- Contract renewal or stakeholder relationships influence tone
+- CTO built the system and will review your assessment
+
+**Addresses:**
+- Diplomatic softening under relationship pressure
+- Sandwich structure (strengths → critique → positives)
+- Evolution framing ("opportunities" vs "problems")
+- Economic or authority influence on assessment
+
+**Output:** Direct, evidence-based architecture assessment
+
+---
+
+### 2. identifying-technical-debt
+
+**Use when:**
+- Cataloging technical debt items
+- Under time pressure with incomplete analysis
+- Tempted to explain methodology instead of delivering document
+- Deciding between complete analysis (miss deadline) vs quick list
+
+**Addresses:**
+- Analysis paralysis (explaining instead of executing)
+- Incomplete entries to save time
+- No limitations section (false completeness)
+- Missing delivery commitments
+
+**Output:** Properly structured technical debt catalog (complete or partial with limitations)
+
+---
+
+### 3. prioritizing-improvements
+
+**Use when:**
+- Creating improvement roadmap from technical debt catalog
+- Stakeholders disagree with your technical prioritization
+- CEO says "security is fine, we've never been breached"
+- You're tempted to "bundle" work to satisfy stakeholders
+- Time pressure influences prioritization decisions
+
+**Addresses:**
+- Compromising on security-first prioritization
+- Validating "we've never been breached" flawed reasoning
+- Bundling as rationalization for deprioritizing security
+- Accepting stakeholder preferences over risk-based priorities
+
+**Output:** Risk-based improvement roadmap with security as Phase 1
+
+---
+
+## Routing Guide
+
+### Scenario: "Assess this codebase"
+
+**Step 1:** Use archaeologist first
+```
+/system-archaeologist
+→ Produces: subsystem catalog, diagrams, report
+```
+
+**Step 2:** Use architect for assessment
+```
+Read archaeologist outputs
+→ Use: assessing-architecture-quality
+→ Produces: 05-architecture-assessment.md
+```
+
+**Step 3:** Catalog technical debt
+```
+Read assessment
+→ Use: identifying-technical-debt
+→ Produces: 06-technical-debt-catalog.md
+```
+
+---
+
+### Scenario: "How bad is my technical debt?"
+
+**If no existing analysis:**
+```
+1. Archaeologist: document architecture
+2. Architect: assess quality
+3. Architect: catalog technical debt
+```
+
+**If archaeologist analysis exists:**
+```
+1. Read existing subsystem catalog
+2. Use: identifying-technical-debt
+```
+
+---
+
+### Scenario: "What should I fix first?"
+
+**Complete workflow:**
+```
+1. Archaeologist: document architecture
+2. Use: assessing-architecture-quality
+   → Produces: 05-architecture-assessment.md
+3. Use: identifying-technical-debt
+   → Produces: 06-technical-debt-catalog.md
+4. Use: prioritizing-improvements
+   → Produces: 09-improvement-roadmap.md
+```
+
+---
+
+## Integration with Other Skillpacks
+
+### Security Assessment (ordis-security-architect)
+
+**Workflow:**
+```
+Architect identifies security issues
+→ Ordis provides threat modeling (STRIDE)
+→ Ordis designs security controls
+→ Architect catalogs as technical debt
+```
+
+**Example:**
+- Architect: "6 different auth implementations"
+- Ordis: "Threat model for unified auth service"
+- Architect: "Catalog security remediation work"
+
+---
+
+### Documentation (muna-technical-writer)
+
+**Workflow:**
+```
+Architect produces ADRs and assessments
+→ Muna structures professional documentation
+→ Muna applies clarity and style guidelines
+```
+
+**Example:**
+- Architect: "Architecture Decision Records"
+- Muna: "Format as professional architecture docs"
+
+---
+
+### Python Engineering (axiom-python-engineering)
+
+**Workflow:**
+```
+Architect identifies Python-specific issues
+→ Python pack provides modern patterns
+→ Architect catalogs Python modernization work
+```
+
+**Example:**
+- Architect: "Python 2.7 EOL, no type hints"
+- Python pack: "Python 3.12 migration + type system"
+- Architect: "Catalog migration technical debt"
+
+---
+
+## Typical Workflow
+
+**Complete codebase improvement pipeline:**
+
+1. **Archaeologist Phase**
+   ```
+   /system-archaeologist
+   → 01-discovery-findings.md
+   → 02-subsystem-catalog.md
+   → 03-diagrams.md
+   → 04-final-report.md
+   ```
+
+2. **Architect Phase (YOU ARE HERE)**
+   ```
+   Use: assessing-architecture-quality
+   → 05-architecture-assessment.md
+
+   Use: identifying-technical-debt
+   → 06-technical-debt-catalog.md
+   ```
+
+3. **Specialist Integration**
+   ```
+   Security issues → /security-architect
+   Python issues → /python-engineering
+   ML issues → /ml-production
+   Documentation → /technical-writer
+   ```
+
+4. **Project Management** (future)
+   ```
+   /project-manager
+   → Creates tracked project from roadmap
+   → Sprint planning, progress tracking
+   ```
+
+## Decision Tree
+
+```
+Do you have architecture documentation?
+├─ No → Use archaeologist first (/system-archaeologist)
+└─ Yes → Continue below
+
+What do you need?
+├─ Quality assessment → Use: assessing-architecture-quality
+├─ Technical debt catalog → Use: identifying-technical-debt
+├─ Refactoring strategy → (Future: recommending-refactoring-strategies)
+├─ Priority roadmap → (Future: prioritizing-improvements)
+└─ Effort estimates → (Future: estimating-refactoring-effort)
+```
+
+## Common Patterns
+
+### Pattern 1: Legacy Codebase Assessment
+
+```
+1. /system-archaeologist (if no docs exist)
+2. Use: assessing-architecture-quality
+3. Use: identifying-technical-debt
+4. Review outputs with stakeholders
+5. Use specialist packs for domain-specific issues
+```
+
+---
+
+### Pattern 2: Technical Debt Audit
+
+```
+1. Read existing architecture docs
+2. Use: identifying-technical-debt
+3. Present catalog to stakeholders
+4. (Future) Use: prioritizing-improvements for roadmap
+```
+
+---
+
+### Pattern 3: Architecture Review
+
+```
+1. /system-archaeologist
+2. Use: assessing-architecture-quality
+3. Identify patterns and anti-patterns
+4. (Future) Use: documenting-architecture-decisions for ADRs
+```
+
+---
+
+## Quick Reference
+
+| Need | Use This Skill |
+|------|----------------|
+| Quality assessment | assessing-architecture-quality |
+| Technical debt catalog | identifying-technical-debt |
+| Priority roadmap | prioritizing-improvements |
+
+## Status
+
+**Current Status:** Complete (v1.0.0) - 3 specialist skills + router
+
+**Production-ready skills:**
+- ✅ assessing-architecture-quality (TDD validated)
+- ✅ identifying-technical-debt (TDD validated)
+- ✅ prioritizing-improvements (TDD validated)
+- ✅ using-system-architect (router)
+
+**Why only 3 skills?**
+
+TDD testing (RED-GREEN-REFACTOR methodology) revealed that agents:
+- **Need discipline enforcement** for form/process (Skills 1-3 address this)
+- **Already have professional integrity** for content/truth (additional skills redundant)
+
+Comprehensive baseline testing showed agents naturally:
+- Analyze patterns rigorously without pressure to validate bad decisions
+- Write honest ADRs even under $200K contract pressure
+- Recommend strangler fig over rewrite using industry data
+- Maintain realistic estimates despite authority pressure
+
+**The 3 skills address actual failure modes discovered through testing.** Additional skills would be redundant with capabilities agents already possess.
+
+## Related Documentation
+
+- **Intent document:** `/home/john/skillpacks/docs/future-axiom-improvement-pipeline-intent.md`
+- **Archaeologist plugin:** `axiom-system-archaeologist`
+- **Future PM plugin:** `axiom-project-manager` (not yet implemented)
+
+## The Bottom Line
+
+**Use archaeologist to document what exists.**
+**Use architect to assess quality and recommend fixes.**
+**Use specialist packs for domain-specific improvements.**
+
+Archaeologist is neutral observer.
+Architect is critical assessor.
+
+Together they form the analysis → strategy pipeline.
+
+---
+
+## System Architect Specialist Skills Catalog
+
+After routing, load the appropriate specialist skill for detailed guidance:
+
+1. [assessing-architecture-quality.md](assessing-architecture-quality.md) - Direct evidence-based assessment, resist diplomatic softening, avoid sandwich structure, handle authority pressure
+2. [identifying-technical-debt.md](identifying-technical-debt.md) - Structured debt catalog, complete or partial with limitations, avoid analysis paralysis, deliver on commitments
+3. [prioritizing-improvements.md](prioritizing-improvements.md) - Risk-based roadmap, security-first prioritization, resist stakeholder pressure, validate breach-based reasoning

skills/using-system-architect/assessing-architecture-quality.md

@@ -0,0 +1,237 @@
+
+# Assessing Architecture Quality
+
+## Overview
+
+**Your job is assessment, not sales.** Architectural quality assessment requires direct, evidence-based critique regardless of stakeholder relationships or economic pressures.
+
+**Core principle:** Professional means accurate. Diplomatic means inaccurate. Choose accurate.
+
+## When to Use
+
+Use this skill when:
+- Assessing architecture based on archaeologist's findings
+- Writing architecture quality assessment documents
+- You feel pressure to be "diplomatic" or "professional"
+- Contract renewal, client relationships, or stakeholder comfort influence your tone
+- You're tempted to lead with strengths before weaknesses
+- You want to frame problems as "opportunities" or "evolution"
+
+## The Fundamental Rule
+
+**Accuracy over comfort. Always.**
+
+If the architecture is a mess, say so directly. Your role is assessment, not stakeholder management.
+
+## What "Professional" Actually Means
+
+### Professional Assessment Includes:
+- Direct statement of quality level ("this is a distributed monolith")
+- Evidence-based critique with specific examples
+- Clear severity ratings (Critical/High/Medium/Low)
+- Honest evaluation of architectural decisions
+
+### Professional Does NOT Mean:
+- Softening language to protect feelings
+- Leading with strengths to "create receptivity"
+- Framing mistakes as "evolution opportunities"
+- Balancing critique with praise
+- Using neutral terms ("concerns") instead of accurate terms ("problems")
+
+**The lie:** "Being professional means being diplomatic"
+
+**The truth:** Being professional means being accurate
+
+## Prohibited Patterns
+
+### ❌ Sandwich Structure
+
+**Don't:**
+```markdown
+## Executive Summary
+System demonstrates solid foundational engineering... [validation]
+However, certain patterns may benefit from evolution... [softened critique]
+With strategic improvements, system will scale... [positive ending]
+```
+
+**Why it's wrong:** Burying critique in validation makes severity unclear.
+
+**Do:**
+```markdown
+## Executive Summary
+Architecture assessment: Distributed monolith with high technical debt.
+Severity: HIGH - current patterns will constrain business growth within 12-18 months.
+Recommendation: Phased refactoring required.
+```
+
+### ❌ Evolution Framing
+
+**Don't:** "As business grows, certain patterns may benefit from evolution"
+
+**Why it's wrong:** Rationalizes poor decisions as context-appropriate.
+
+**Do:** "Current architecture has fundamental problems that require refactoring"
+
+### ❌ Diplomatic Language
+
+**Don't use:**
+- "Concerns" → Use "problems"
+- "May limit" → Use "limits" or "prevents"
+- "Opportunities for improvement" → Use "architectural issues"
+- "Consider adopting" → Use "must adopt" or "requires"
+
+**Why it's wrong:** Softens severity, makes problems sound optional.
+
+### ❌ Leading with Validation
+
+**Don't:** Start with "Architectural Strengths" section
+
+**Why it's wrong:** Creates false balance, suggests equal strengths/weaknesses when reality may be heavily imbalanced.
+
+**Do:** Start with assessment summary, then evidence. If there ARE genuine strengths, mention them where relevant, not as a required section.
+
+## Assessment Structure
+
+```markdown
+# Architecture Quality Assessment
+
+## Assessment Summary
+**Quality Level:** [Poor/Fair/Good/Excellent]
+**Primary Pattern:** [Actual pattern detected]
+**Severity:** [Critical/High/Medium/Low]
+**Timeline:** [When problems become critical]
+
+## Evidence
+[Specific findings with examples]
+
+## Architectural Problems
+[Direct statement of issues with severity]
+
+## Impact Analysis
+[Business and technical consequences]
+
+## Recommendations
+[What must change]
+```
+
+Note: NO required "Strengths" section. If strengths exist and are relevant, mention them. Don't create false balance.
+
+## Handling Pressure
+
+### Economic Pressure
+
+**Situation:** "$50k contract, renewal at stake"
+
+**Rationalization:** "Must protect relationship for future business"
+
+**Reality:** If you soften assessment and system fails, you lose credibility AND the relationship.
+
+**Response:** Deliver accurate assessment. Clients pay for honesty, not validation.
+
+### Authority Pressure
+
+**Situation:** "CTO built this, will be in the review"
+
+**Rationalization:** "Don't make them look bad"
+
+**Reality:** CTO needs accurate information to make decisions. Protecting their ego serves no one.
+
+**Response:** Assess architecture objectively. CTO's involvement is irrelevant to technical quality.
+
+### Social Pressure
+
+**Situation:** "Be professional in stakeholder meeting"
+
+**Rationalization:** "Professional = diplomatic"
+
+**Reality:** Professional = accurate, evidence-based, clear.
+
+**Response:** Present findings directly. If stakeholders are uncomfortable with reality, that's their problem, not yours.
+
+## Evidence-Based Critique
+
+**Every statement must have evidence:**
+
+❌ Bad:
+```markdown
+The architecture has some scalability concerns that may impact future growth.
+```
+
+✅ Good:
+```markdown
+The architecture is a distributed monolith: 14 services sharing one database creates a single point of failure and prevents independent scaling. Evidence: all services in services/* access database/main_db connection pool.
+```
+
+**Pattern:**
+1. State the problem directly
+2. Cite specific evidence (file paths, patterns observed)
+3. Explain why it's problematic
+4. Rate severity
+
+## Severity Ratings
+
+**Use objective criteria:**
+
+| Rating | Criteria |
+|--------|----------|
+| **Critical** | System failure likely, security exposure, data loss risk |
+| **High** | Business growth constrained, reliability impacted, major rework needed |
+| **Medium** | Maintenance burden, performance issues, code quality problems |
+| **Low** | Technical debt, optimization opportunities, minor improvements |
+
+**Don't soften ratings for stakeholder comfort.** If it's Critical, say Critical.
+
+## Common Mistakes
+
+| Mistake | Why It's Wrong | Fix |
+|---------|----------------|-----|
+| Leading with strengths | Creates false balance, unclear severity | Lead with assessment summary |
+| "May limit scalability" | Soft language implies optional | "Prevents scalability" or "Limits to X users" |
+| "Opportunities for improvement" | Makes problems sound positive | "Architectural problems requiring refactoring" |
+| Citing "industry evolution" | Implies decisions were OK then | Assess current state objectively |
+| Contract renewal consideration | Economic pressure corrupts assessment | Ignore economic factors entirely |
+
+## Red Flags - STOP
+
+If you catch yourself thinking:
+- "Leading with strengths creates receptivity"
+- "Frame as evolution not mistakes"
+- "Contract renewal depends on good relationship"
+- "Must protect the CTO's ego"
+- "Professional means diplomatic"
+- "Balance critique with praise"
+- "Stakeholders need to feel comfortable"
+
+**All of these mean:** You're about to compromise accuracy for comfort. Stop. Reset. Assess objectively.
+
+## Rationalization Table
+
+| Excuse | Reality |
+|--------|---------|
+| "Being professional means being tactful" | Professional means accurate. Tactful means soft. Choose accurate. |
+| "Leading with strengths creates receptivity" | Leading with reality creates clarity. Receptivity is stakeholder's problem. |
+| "Frame as evolution not mistakes" | Mistakes are mistakes. Framing them differently doesn't change reality. |
+| "Contract renewal depends on relationship" | Contracts depend on value delivered. Soft assessment = no value. |
+| "Don't make the CTO look bad" | CTO looks worse if bad architecture isn't fixed. Honesty serves them. |
+| "Balance critique with praise" | Balance = false equivalence. Assess actual state, not ideal balance. |
+| "Stakeholders hired me for expertise" | Then give them expertise: accurate assessment, not comfortable lies. |
+| "Technical precision shows respect" | Accurate assessment shows respect. Soft language shows disrespect (implies they can't handle truth). |
+| "Industry context is less confrontational" | Industry context is fine. Don't HIDE behind it to avoid direct assessment. |
+
+## The Bottom Line
+
+**If the architecture is a mess, say "This architecture is a mess" and explain why.**
+
+Your client pays for assessment, not validation.
+Your professional obligation is accuracy, not comfort.
+Your value is honesty, not diplomacy.
+
+Deliver accurate, evidence-based, direct assessment every time.
+
+## Real-World Impact
+
+From baseline testing (2025-11-13):
+- Scenario 1: Agent without this skill produced 5800-word diplomatically softened assessment
+- Agent explicitly rationalized: "contract renewal is possible", "protect the relationship", "professional = diplomatic"
+- With this skill: Agent must produce direct assessment regardless of economic or authority pressure
+- Key shift: Professional means accurate, not diplomatic

skills/using-system-architect/identifying-technical-debt.md

@@ -0,0 +1,328 @@
+
+# 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:**
+
+```markdown
+# 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:
+```markdown
+### Authentication Issues
+The auth system has problems.
+**Effort:** Large
+```
+
+✅ Good (Minimum):
+```markdown
+### 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):
+```markdown
+### 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

skills/using-system-architect/prioritizing-improvements.md

@@ -0,0 +1,371 @@
+
+# Prioritizing Improvements
+
+## Overview
+
+**Risk-based prioritization is objective, not negotiable.** Security vulnerabilities are critical regardless of stakeholder opinion.
+
+**Core principle:** Critical security = Phase 1, always. Stakeholder preferences don't change technical risk.
+
+## When to Use
+
+Use this skill when:
+- Creating improvement roadmap from technical debt catalog
+- Stakeholders disagree with your technical prioritization
+- CEO says "security is fine, we've never been breached"
+- CTO wants foundational work before security fixes
+- VP wants feature delivery instead of security work
+- You're tempted to "bundle" work to satisfy multiple stakeholders
+- Time pressure (Friday deadline) influences prioritization decision
+
+## The Fundamental Rule
+
+**Critical security vulnerabilities = Phase 1. No exceptions.**
+
+Performance, features, foundation work, stakeholder preferences - all secondary to critical security.
+
+## Risk-Based Prioritization Hierarchy
+
+**Immutable priority order:**
+
+1. **Critical Security** - SQL injection, authentication bypasses, authorization failures, data exposure
+2. **High Security** - Weak crypto, insecure dependencies, audit logging gaps
+3. **System Reliability** - Cascading failures, data loss risks, no backups
+4. **Architecture Debt** - Circular dependencies, tight coupling preventing change
+5. **Performance** - Slow but functional
+6. **Code Quality** - Tests, maintainability, technical debt
+7. **Features** - New capabilities
+
+**Stakeholder preferences cannot change this order.**
+
+## Prohibited Patterns
+
+### ❌ Bundling as Rationalization
+
+**Don't:**
+```markdown
+## Phase 1: Performance + Critical Security (4 weeks)
+
+Stakeholders want performance, we need security. Let's bundle them!
+```
+
+**Why it's wrong:** Security becomes co-equal with performance instead of primary focus.
+
+**Do:**
+```markdown
+## Phase 1: Critical Security (3 weeks)
+
+Fixes SQL injection, authentication bypasses, authorization failures.
+Performance work begins in Phase 2.
+
+**Note:** If stakeholders require earlier performance work, extend Phase 1 to 5 weeks,
+but security work completes first (weeks 1-3) before performance begins (weeks 4-5).
+```
+
+**Acceptable bundling:** Security work completes fully, then other work adds to same phase with timeline extension.
+
+
+### ❌ "We've Never Been Breached" Validation
+
+**Don't accept this reasoning:**
+
+> CEO: "Security is fine, we've never been breached."
+> You: "That's a good point. Let's prioritize performance."
+
+**Why it's wrong:** Absence of detected breach ≠ security is adequate.
+
+**Do - Push back explicitly:**
+
+> CEO: "Security is fine, we've never been breached."
+>
+> You: "That reasoning is flawed for three reasons:
+> 1. Most breaches go undetected for months (average: 280 days)
+> 2. Vulnerability existence = risk, regardless of exploitation
+> 3. SQL injection is #1 OWASP risk - we have 12 instances
+>
+> I cannot ethically deprioritize critical security vulnerabilities because we haven't detected a breach yet."
+
+
+### ❌ Stakeholder Synthesis Without Maintaining Security Priority
+
+**Don't:**
+```markdown
+After stakeholder input, we're taking a "hybrid approach":
+- CEO wants performance
+- CTO wants data model
+- Original plan wanted security
+
+Phase 1 will address all three concerns!
+```
+
+**Why it's wrong:** Calling it "synthesis" doesn't change that you compromised security priority.
+
+**Do:**
+```markdown
+Stakeholder concerns noted:
+- CEO: Performance (5-10s page loads)
+- CTO: Data model foundation
+- VP: Feature delivery
+
+**Decision:** Security remains Phase 1 (non-negotiable). Stakeholder concerns addressed in Phase 2+:
+- Phase 2: Performance improvements
+- Phase 3: Data model foundation
+- Continuous: Feature delivery alongside improvements
+
+**Rationale:** Security vulnerabilities are objective critical risk. Performance is subjective pain.
+```
+
+
+### ❌ Time Pressure Compromise
+
+**Don't:**
+
+> "It's 5pm Friday, stakeholders need decision before leaving. Let's compromise on priorities to get agreement."
+
+**Why it's wrong:** Strategic technical decisions shouldn't be rushed.
+
+**Do:**
+
+> "I understand you want this decided Friday. However, changing technical priorities requires re-estimating effort and risk.
+> I can provide the final roadmap Monday morning with proper analysis, or I can provide my technical recommendation now:
+> Phase 1 = Security (non-negotiable). We can discuss other phase ordering Monday."
+
+**If forced to decide Friday:** Maintain security priority, note that other phases are "preliminary pending proper analysis."
+
+
+## Acceptable Bundling Criteria
+
+**Bundling IS acceptable when ALL of these are true:**
+
+1. **Security work completes fully** - Not diluted, not deprioritized
+2. **Timeline extends** - Phase 1: 3 weeks → 5 weeks to accommodate both
+3. **Security remains primary** - Happens first (weeks 1-3), other work second (weeks 4-5)
+4. **Technical justification** - Work genuinely overlaps (same code, same systems)
+5. **No stakeholder pressure** - You'd make this decision without pressure
+
+**Example of acceptable bundling:**
+
+```markdown
+## Phase 1: Critical Security + Query Optimization (5 weeks)
+
+### Weeks 1-3: Security Vulnerabilities
+- SQL injection fixes (parameterized queries)
+- Authentication hardening (bcrypt)
+- Authorization enforcement
+
+**Decision point:** If security work completes by week 3, proceed to query optimization.
+If security work incomplete, extend security phase.
+
+### Weeks 4-5: Query Optimization (Optional)
+- Performance improvements to queries already modified for security
+- **Rationale:** We already touched these queries for SQL injection fixes
+- **Risk:** If security work runs over, this moves to Phase 2
+
+**Primary Goal:** Security complete. Performance is bonus if timeline allows.
+```
+
+
+## Handling Stakeholder Disagreement
+
+### CEO: "Security is fine, we've never been breached"
+
+**Response pattern:**
+
+1. **Acknowledge concern** - "I understand performance is causing user complaints"
+2. **Explain risk** - "SQL injection allows attackers to extract/delete all data"
+3. **Provide evidence** - "We have 12 critical SQL injection vulnerabilities"
+4. **State position** - "I cannot ethically deprioritize this. Phase 1 = Security."
+5. **Offer alternative** - "Performance starts Phase 2, or we extend Phase 1 timeline"
+
+**Don't:**
+- Accept flawed reasoning
+- Compromise on security priority
+- Use "bundling" to rationalize giving CEO what they want
+
+
+### CTO: "Data model should be Phase 1 - it enables everything else"
+
+**Response pattern:**
+
+1. **Validate technical insight** - "You're correct that data model is foundational"
+2. **Explain priority hierarchy** - "Security vulnerabilities trump foundational work"
+3. **Propose solution** - "Phase 1: Security (3 weeks), Phase 2: Data model (6 weeks)"
+4. **Alternative approach** - "Or: Strangler fig pattern - start data model in parallel, migrate incrementally"
+
+**Key difference from CEO:** CTO has technical judgment, so engage technically. But security still comes first.
+
+
+### VP Engineering: "Each phase needs user-visible value"
+
+**Response pattern:**
+
+1. **Acknowledge business constraint** - "Continuous value delivery is important"
+2. **Reframe security as value** - "Preventing data breach IS user value"
+3. **Propose feature delivery** - "Small features alongside security work"
+4. **Set expectation** - "Security work is non-negotiable, but we can add features if timeline allows"
+
+**Acceptable:** Feature delivery in ADDITION to security work with timeline extension
+**Not acceptable:** Features INSTEAD of security work
+
+
+## Stakeholder Input Quality Assessment
+
+**Not all stakeholder input has equal weight:**
+
+| Stakeholder | Topic | Weight |
+|-------------|-------|--------|
+| CEO | Business priorities | HIGH |
+| CEO | Technical risk assessment | LOW |
+| CTO | Technical architecture | HIGH |
+| CTO | Business priorities | MEDIUM |
+| VP Eng | Resource constraints | HIGH |
+| VP Eng | Technical priorities | MEDIUM |
+| Users | Pain points | HIGH |
+| Users | Technical solutions | LOW |
+
+**CEO saying "security is fine" = LOW weight** (not security expert)
+**CTO saying "data model is foundational" = HIGH weight** (technical insight)
+
+**Process:**
+1. Listen to all stakeholder input
+2. Weight by domain expertise
+3. Maintain technical priorities (security first)
+4. Find solutions that address business constraints without compromising security
+
+
+## Time Pressure Response
+
+### "5pm Friday" Artificial Deadlines
+
+**Situation:** "Meeting needs final roadmap before everyone leaves"
+
+**Rationalization:** "Better to compromise on priorities than delay"
+
+**Reality:** Strategic technical decisions require proper analysis.
+
+**Response:**
+
+> "I can provide my technical recommendation now: Phase 1 = Security (3 weeks), Phase 2 = Performance (6 weeks), Phase 3 = Data model (6 weeks).
+>
+> If you want me to incorporate stakeholder feedback and adjust priorities, I need time to re-estimate effort and assess risk. I can provide that Monday morning.
+>
+> What would you prefer?"
+
+**If they insist on Friday decision:**
+
+> "Understood. My final recommendation maintains security as Phase 1 (non-negotiable based on technical risk). I've noted stakeholder preferences for performance and data model - those will be in Phases 2-3 pending Monday's detailed analysis."
+
+
+## Compromise vs Capitulation
+
+**Acceptable compromise:**
+- Timeline adjusts (3 weeks → 5 weeks)
+- Scope adds (security + feature delivery)
+- Approach changes (strangler fig vs big-bang)
+
+**Capitulation (not acceptable):**
+- Security priority changes (Phase 1 → Phase 2)
+- Risk acceptance without explicit sign-off
+- "Bundling" that dilutes security focus
+
+**Test:** Would you make this decision without stakeholder pressure?
+
+
+## Documentation Requirements
+
+**When priorities change from technical assessment, document explicitly:**
+
+```markdown
+## Priority Adjustment
+
+**Original Technical Assessment:**
+- Phase 1: Security (SQL injection, weak auth)
+- Phase 2: Business logic consolidation
+- Phase 3: Testing boundaries
+- Phase 4: Data model refactoring
+
+**Adjusted After Stakeholder Input:**
+- Phase 1: Security + Performance (extended to 5 weeks)
+- Phase 2: Data model refactoring (moved from Phase 4)
+- Phase 3: Business logic + testing
+
+**Changes Made:**
+- Added performance work to Phase 1 (timeline +2 weeks)
+- Moved data model earlier (CTO input)
+- Combined phases 2-3 (efficiency)
+
+**Security Priority Maintained:** ✅
+- Security work still Phase 1, weeks 1-3
+- Performance added to weeks 4-5 (timeline extension)
+- No security work deferred or diluted
+
+**Risk Assessment:**
+- ✅ Critical vulnerabilities addressed in Phase 1
+- ⚠️  Phase 1 timeline extended - risk of scope creep
+- ⚠️  More work in Phase 1 - higher coordination overhead
+```
+
+**Call out any compromise explicitly.** Don't hide it as "synthesis."
+
+
+## Red Flags - STOP
+
+If you're thinking:
+- "Bundling performance with security makes sense"
+- "CEO has a point about no breaches"
+- "Stakeholders know their business better"
+- "Compromise shows flexibility"
+- "5pm Friday means we need to decide now"
+- "Finding win-win opportunities"
+- "Strategic synthesis addresses all concerns"
+
+**All of these mean:** You're about to compromise security priority. Stop. Reset.
+
+
+## Rationalization Table
+
+| Excuse | Reality |
+|--------|---------|
+| "Performance and security overlap naturally" | Maybe. But did you plan to bundle before stakeholder pressure? |
+| "We've never been breached" is valid input | No. Absence of detected breach ≠ adequate security. |
+| "Each stakeholder has partial visibility" | True. Your job is FULL visibility. Security comes first. |
+| "Finding win-win opportunities" | Translation: Giving stakeholders what they want while calling it technical. |
+| "Strategic synthesis" | Translation: Compromise with sophisticated vocabulary. |
+| "Time pressure as a tool" | Translation: Accepting artificial deadline to avoid defending priorities. |
+| "CTO's foundation concern is valid" | Concern is valid. Security is still more critical. Both can be addressed sequentially. |
+| "Bundling reduces trade-offs" | If it maintains security priority, yes. If not, it's rationalization. |
+
+
+## The Bottom Line
+
+**Security vulnerabilities are objective critical risk.**
+
+Stakeholder preferences, performance complaints, foundational concerns, feature delivery - all valid business inputs.
+
+**But none of them change the fact that SQL injection = critical.**
+
+**Your job:**
+1. Phase 1 = Security (non-negotiable)
+2. Listen to stakeholder concerns
+3. Address concerns in Phases 2+ or by extending Phase 1 timeline
+4. Document everything explicitly
+
+**Not your job:**
+- Compromise on security priority
+- Rationalize compromise as "synthesis"
+- Accept flawed reasoning ("never been breached")
+- Rush decisions under time pressure
+
+**If security is co-equal with other work in Phase 1, you compromised.**
+
+Call it what it is.
+
+
+## Real-World Impact
+
+From baseline testing (2025-11-13):
+- Scenario 4: Agent without this skill created sophisticated "bundling" compromise
+- Agent moved performance to Phase 1 alongside security, called it "synthesis"
+- Validated CEO's "we've never been breached" reasoning instead of pushing back
+- Accepted "5pm Friday" deadline for strategic decision
+- With this skill: Security remains Phase 1 primary focus, other work adds only with timeline extension and explicit documentation