Using System Architect

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?"

How to Access Reference Sheets

IMPORTANT: All reference sheets are located in the SAME DIRECTORY as this SKILL.md file.

When this skill is loaded from: skills/using-system-architect/SKILL.md

Reference sheets like assessing-architecture-quality.md are at: skills/using-system-architect/assessing-architecture-quality.md

NOT at: skills/assessing-architecture-quality.md ← WRONG PATH

When you see a link like [assessing-architecture-quality.md](assessing-architecture-quality.md), read the file from the same directory as this SKILL.md.

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"

Delivery Manager (axiom-program-management, /program-management):

• Execution tracking, flow metrics, and forecasting
• Dependency, risk and RAID management
• Governance cadence and benefits realization
• "Here's how we'll track the fixes"

Product Owner (axiom-product-management, /product-management):

• Whether the fix is worth making, and for whom
• Bets, PRDs, and falsifiable acceptance criteria
• "Here's why this one and not that one"

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-quality-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-quality-assessment.md
3. Use: identifying-technical-debt
   → Produces: 06-technical-debt-catalog.md
4. Use: prioritizing-improvements
   → Produces: 07-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-quality-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. Delivery Management

   /program-management
   → Turns the roadmap into sequenced, tracked delivery
   → Flow metrics, dependencies, RAID, forecasting
   /product-management
   → Decides which fixes are worth making, and for whom
   

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
├─ Priority roadmap → Use: prioritizing-improvements
├─ Refactoring strategy → Out of scope (use /security-architect for security remediation strategy; use /solution-architect for forward design)
└─ Effort estimates → Out of scope (defer to project-management tooling; not provided by this pack)

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. Use: prioritizing-improvements for roadmap

Pattern 3: Architecture Review

1. /system-archaeologist
2. Use: assessing-architecture-quality
3. Identify patterns and anti-patterns
4. For ADRs, hand off to `/technical-writer` (muna-technical-writer:create-adr) or `/solution-architect`

Quick Reference

Scope Rationale

Production-ready skills:

• assessing-architecture-quality (TDD validated)
• identifying-technical-debt (TDD validated)
• prioritizing-improvements (TDD validated)
• using-system-architect (router)

(Version is tracked in plugin.json, not here.)

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

• Archaeologist plugin: axiom-system-archaeologist (/system-archaeologist)
• Delivery plugin: axiom-program-management (/program-management)
• Product plugin: axiom-product-management (/product-management)
• Distributed-systems architecture: axiom-distributed-systems (/distributed-systems)

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 - Direct evidence-based assessment, resist diplomatic softening, avoid sandwich structure, handle authority pressure
2. identifying-technical-debt.md - Structured debt catalog, complete or partial with limitations, avoid analysis paralysis, deliver on commitments
3. prioritizing-improvements.md - Risk-based roadmap, security-first prioritization, resist stakeholder pressure, validate breach-based reasoning