/setup-architect

Initial System Analysis

Reading this template for the first time? It is intentionally comprehensive — most teams won't fill every section on their first pass. The minimum viable initial analysis fills only:

• Executive Summary (with Overall Assessment + Key Findings)
• System Overview → Project Information + Technology Stack
• Individual Member Analyses (one paragraph per active team member)
• Collaborative Synthesis (cross-cutting themes that emerged)
• Recommendations (the top 3-5, prioritized)
• Suggested Next Steps

The remaining sections (Architectural Health Assessment, Technical Debt Inventory, Risk Assessment, Success Metrics, Appendix) are valuable for mature teams revisiting the analysis or for high-stakes systems. Skip them on the first pass — they can be filled in later as the framework gets used.

The orchestrator (setup-architect skill, post-1.5.0) populates this document by dispatching subagent calls and aggregating the returned reviews. You should not need to write it by hand.

Project: [Project Name] Date: [YYYY-MM-DD] Analysis Type: Initial Setup Assessment Analysts: [List all architecture members participating]

Executive Summary

Required for minimum viable analysis.

[Write 2-3 paragraphs providing a high-level overview of the system being analyzed. Include:

• What the system does (purpose and domain)
• Primary technologies and stack
• Current state and maturity level
• Overall architectural health ]

Overall Assessment: [Excellent | Good | Adequate | Needs Attention]

Key Findings:

• [Major finding 1]
• [Major finding 2]
• [Major finding 3]

Critical Recommendations:

• [Top priority recommendation]
• [Second priority recommendation]

System Overview

Required for minimum viable analysis (Project Information + Technology Stack subsections).

Project Information

Primary Language(s): [e.g., JavaScript/TypeScript, Python, Ruby]

Frameworks: [e.g., React, Rails, Django, Express]

Architecture Style: [e.g., Monolith, Microservices, Serverless, Hybrid]

Deployment: [e.g., Heroku, AWS, Docker, Kubernetes]

Team Size: [Number of developers]

Project Age: [e.g., 2 years, New project, Legacy system]

Technology Stack

Frontend:

• [Technology 1]
• [Technology 2]

Backend:

• [Technology 1]
• [Technology 2]

Database:

• [Primary database]
• [Cache layer if any]

Infrastructure:

• [Hosting/cloud provider]
• [CI/CD tools]
• [Monitoring/observability]

Project Structure

[Provide high-level directory structure]
/
├── src/
│   ├── components/
│   ├── services/
│   └── ...
├── tests/
└── ...

Key Observations:

• [Structure observation 1]
• [Structure observation 2]

Individual Member Analyses

Required for minimum viable analysis. One paragraph per active team member is enough on a first pass.

[Member Name] - [Title]

Perspective: [Their specialized viewpoint]

Current State Assessment

[Detailed analysis from this member's perspective. Include:

• What they examined
• How they evaluated it
• What they discovered ]

Strengths Identified

1. [Strength]: [Why this is valuable and how it benefits the project]

2. [Strength]: [Description]

3. [Strength]: [Description]

Concerns Raised

1. [Concern] (Impact: High | Medium | Low)

   • Issue: [What's problematic]
   • Why It Matters: [Impact on project/team]
   • Recommendation: [Suggested action]

2. [Concern] (Impact: High | Medium | Low)

   • Issue: [Description]
   • Why It Matters: [Impact]
   • Recommendation: [Action]

Initial Recommendations

1. [Recommendation] (Priority: Critical | Important | Nice-to-Have, Effort: Small | Medium | Large)

   • What: [Action to take]
   • Why: [Benefit or risk addressed]
   • How: [Implementation approach]

2. [Recommendation] (Priority, Effort)

   • [Details]

[Repeat for each architecture member]

Collaborative Synthesis

Required for minimum viable analysis. Surface 2-4 cross-cutting themes that appeared in 3+ member analyses.

[After individual analyses, synthesize findings across all members]

Common Themes

Strengths (What multiple members praised):

1. [Common strength 1]
2. [Common strength 2]

Concerns (What multiple members flagged):

1. [Common concern 1]
2. [Common concern 2]

Disagreements (Where members had different views):

• Topic: [Topic of disagreement]
  • [Member 1]: [Their view]
  • [Member 2]: [Their view]
  • Resolution: [How to reconcile or way forward]

Prioritized Findings

Critical (Address Immediately):

1. [Finding]: [Why critical, impact if not addressed]
2. [Finding]: [Details]

Important (Address in Near Term):

1. [Finding]: [Why important]
2. [Finding]: [Details]

Nice-to-Have (Consider for Future):

1. [Finding]: [Why beneficial but not urgent]
2. [Finding]: [Details]

Architectural Health Assessment

Optional on first pass. Recommended for mature teams revisiting the analysis or for high-stakes systems.

Code Quality

Rating: [1-10]

Observations:

• [Observation about code organization]
• [Observation about code clarity]
• [Observation about technical debt]

Key Issues:

• [Issue 1]
• [Issue 2]

Testing

Coverage: [Percentage if known, or qualitative assessment]

Rating: [1-10]

Observations:

• [Test presence and quality]
• [Test types (unit, integration, e2e)]
• [Test infrastructure]

Gaps:

• [Gap 1]
• [Gap 2]

Documentation

Rating: [1-10]

Observations:

• [README quality]
• [API documentation]
• [Architecture documentation]
• [Code comments]

Missing:

• [What documentation is missing]

Security

Rating: [1-10]

Observations:

• [Authentication/authorization approach]
• [Data protection measures]
• [Known vulnerabilities]

Concerns:

• [Security concern 1]
• [Security concern 2]

Performance

Rating: [1-10]

Observations:

• [Performance characteristics]
• [Scalability considerations]
• [Known bottlenecks]

Concerns:

• [Performance concern 1]
• [Performance concern 2]

Maintainability

Rating: [1-10]

Observations:

• [How easy is it to change?]
• [Developer onboarding experience]
• [Build/deploy process]

Challenges:

• [Maintainability challenge 1]
• [Maintainability challenge 2]

Technical Debt Inventory

Optional on first pass. Most useful for established systems where debt has accumulated.

High Priority Debt

1. [Debt Item]

   • Impact: [How it affects development]
   • Effort to Resolve: [Small | Medium | Large]
   • Recommendation: [When and how to address]

2. [Debt Item]: [Details]

Medium Priority Debt

1. [Debt Item]: [Details]
2. [Debt Item]: [Details]

Low Priority Debt

1. [Debt Item]: [Details]

Risk Assessment

Optional on first pass.

Technical Risks

1. [Risk] (Likelihood: High/Medium/Low, Impact: High/Medium/Low)

   • Description: [What could go wrong]
   • Impact: [Consequences if it happens]
   • Mitigation: [How to reduce or eliminate]

2. [Risk] (Likelihood, Impact)

   • [Details]

Business Risks

1. [Risk] (Likelihood, Impact)
   • [Details]

Operational Risks

1. [Risk] (Likelihood, Impact)
   • [Details]

Recommendations

Required for minimum viable analysis. Top 3-5 prioritized recommendations is sufficient for a first pass.

Immediate Actions (0-2 Weeks)

1. [Action]

   • Why: [Problem being solved]
   • How: [Implementation approach]
   • Owner: [Who should do this]
   • Success Criteria: [How to know it's done]
   • Effort: [Time estimate]

2. [Action]: [Details]

Short-Term Actions (2-8 Weeks)

1. [Action]

   • Why: [Benefit]
   • How: [Approach]
   • Owner: [Responsible party]
   • Success Criteria: [Completion criteria]
   • Effort: [Estimate]

2. [Action]: [Details]

Long-Term Initiatives (2-6 Months)

1. [Initiative]

   • Why: [Strategic value]
   • How: [High-level roadmap]
   • Owner: [Responsible party]
   • Success Criteria: [Long-term goals]
   • Effort: [Estimate]

2. [Initiative]: [Details]

Success Metrics

Optional on first pass. Useful when the recommendations have known measurable outcomes; most first-pass analyses defer this.

Define measurable targets to track improvement:

1. [Metric Name]

   • Baseline: [Current value]
   • Target: [Desired value]
   • Timeline: [When to achieve]
   • How to Measure: [Measurement method]

2. [Metric]: Baseline → Target (Timeline)

3. [Metric]: Baseline → Target (Timeline)

[Examples:

• Test Coverage: 30% → 70% (3 months)
• Build Time: 10 min → 3 min (6 weeks)
• Documentation Score: 4/10 → 8/10 (2 months) ]

Suggested Next Steps

Required for minimum viable analysis.

Based on this initial analysis:

1. [Step 1]: [Specific actionable next step]
2. [Step 2]: [Next step]
3. [Step 3]: [Next step]

Documentation:

• Create ADRs for key architectural decisions identified
• Document existing patterns in ADRs
• Schedule regular architecture reviews

Process:

• Establish review cadence (quarterly recommended)
• Define ADR creation criteria
• Set up architecture recalibration process

Appendix

Optional on first pass. Use for raw notes, code samples, or evidence supporting findings above.

Analysis Methodology

This analysis was conducted using the AI Software Architect framework. Each member analyzed the system from their specialized perspective, then collaborated to synthesize findings and prioritize recommendations.

Members Participating:

• [Member 1] - [Role]
• [Member 2] - [Role]
• [etc.]

Glossary

[Define project-specific terms or acronyms used in analysis]

• [Term]: [Definition]
• [Acronym]: [Expansion and meaning]

Analysis Complete Next Review: [Suggested date - typically 3-6 months after setup]