| name | assessing-architecture-quality |
| description | Use when assessing codebase architecture and you feel pressure to soften critique, lead with strengths, or frame problems diplomatically - provides evidence-based critical assessment resisting relationship and economic pressures |
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:
## 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:
## 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
# 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:
The architecture has some scalability concerns that may impact future growth.
✅ Good:
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:
- State the problem directly
- Cite specific evidence (file paths, patterns observed)
- Explain why it's problematic
- 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
