Architecture Gap Analysis

Produce a prioritized, evidence-backed inventory of architectural gaps, risks, and technical debt in a brownfield codebase. This skill compares the actual system state (from AS_IS_SYSTEM_MODEL.md and REVERSE_PRD.md) against architectural best practices, security standards, and maintainability criteria to identify where the system falls short.

When to Use This Skill

• After completing Codebase Discovery and Reverse PRD to evaluate what was found
• When stakeholders need a prioritized list of architectural problems
• To establish the case for refactoring or migration investment
• As input to Target Architecture design (what needs to change)
• When preparing technical debt reduction proposals

Pipeline Position

[AS_IS_SYSTEM_MODEL.md + REVERSE_PRD.md + Codebase] --> **ARCHITECTURE GAP ANALYSIS** --> [ARCH_GAPS_AND_RISKS.md] --> Target Architecture --> ...

Input: AS_IS_SYSTEM_MODEL.md, REVERSE_PRD.md, actual codebase (via Read/Glob/Grep) Output: ARCH_GAPS_AND_RISKS.md written to artifacts directory

Artifact Template

The output artifact follows the standard artifact template:

# [ARTIFACT TITLE]
## Summary
## Inputs
## Outputs
## Assumptions
## Open Questions
## Main Content
## Acceptance Criteria

Process

Step 1: Read Upstream Artifacts

1. Read AS_IS_SYSTEM_MODEL.md to understand:
   • Component inventory (COMP-NNNN)
   • Technology stack and versions
   • Dependency map (internal and external)
   • Data flow patterns
   • Configuration and environment setup
2. Read REVERSE_PRD.md to understand:
   • Feature inventory (REQ-NNNN)
   • User flows (FLOW-NNNN)
   • Data entities (ENT-NNNN)
   • Integration points (INT-NNNN)
   • Dead code inventory (DEAD-NNNN)
3. Extract key findings, component boundaries, and integration points for targeted analysis

Step 2: Analyze Architecture Gaps

Systematically evaluate the codebase against architectural quality attributes.

2a: Missing Abstractions

1. Grep for direct dependency violations:
   • Controllers/handlers directly querying databases (skipping service layer)
   • Business logic in route handlers instead of service classes
   • Cross-component imports that bypass defined interfaces
2. Check for missing patterns:
   • No repository/data access layer between services and database
   • No middleware for cross-cutting concerns (logging, auth, error handling)
   • No dependency injection or inversion of control
3. Evidence: Cite specific files where abstraction is missing

> Route handler directly executes SQL query instead of using a service layer [src/routes/orders.ts:45-60]

2b: Tight Coupling

1. Analyze dependency map from AS_IS_SYSTEM_MODEL.md:
   • Components with excessive inbound or outbound dependencies
   • Circular dependencies (already flagged in discovery)
   • God objects or god modules (files with too many responsibilities)
2. Grep for coupling indicators:
   • Shared mutable state between components
   • Direct file path references across module boundaries
   • Hardcoded URLs or service addresses
3. Measure: Count import statements per file for hotspot detection

2c: Security Anti-Patterns

1. Grep for known security issues:
   • Hardcoded secrets: password =, secret =, api_key =, token = in source files
   • SQL injection risk: String concatenation in queries ("SELECT.*" +, f-strings with SQL)
   • Missing input validation: Routes without validation middleware
   • Insecure defaults: cors({ origin: '*' }), debug: true in production config
   • Missing authentication: Routes without auth middleware
   • Weak cryptography: md5(, sha1( for passwords
2. Check for security infrastructure:
   • HTTPS enforcement
   • Rate limiting
   • CSRF protection
   • Content Security Policy headers
   • Secrets management (env vars vs. hardcoded)

2d: Performance Bottlenecks

1. Grep for performance anti-patterns:
   • N+1 query patterns: Database calls inside loops
   • Missing indexes: Large table queries without apparent index support
   • Synchronous blocking: sync operations in async contexts
   • Missing caching: Repeated expensive computations without memoization
   • Unbounded queries: SELECT * without LIMIT, missing pagination
   • Large payload serialization without streaming
2. Check for performance infrastructure:
   • Caching layer (Redis, Memcached, in-memory)
   • Connection pooling
   • Request timeouts
   • Circuit breakers for external calls

2e: Maintainability Issues

1. Check for code organization:
   • Consistent file naming conventions (or lack thereof)
   • Module boundary clarity
   • Code duplication (Grep for repeated patterns)
   • File size distribution (flag files over 500 lines)
2. Check for development practices:
   • Test presence and coverage gaps
   • Linting configuration
   • Type safety (TypeScript strict mode, Python type hints)
   • Documentation presence (JSDoc, docstrings, comments)
3. Check for operational readiness:
   • Logging consistency and structure
   • Error handling patterns (global vs. per-handler)
   • Health check endpoints
   • Graceful shutdown handling

2f: Reliability Concerns

1. Check for fault tolerance:
   • Error recovery patterns (retry, circuit breaker, fallback)
   • Transaction management (database, distributed)
   • Data validation at boundaries
   • Idempotency for non-GET operations
2. Check for observability:
   • Structured logging
   • Metrics collection
   • Distributed tracing
   • Alerting configuration

Step 3: Build Gap Inventory

For each identified gap, create a structured entry.

Gap format:

### GAP-0001: [Title]
- **Priority**: P0 | P1 | P2
- **Category**: Architecture | Security | Performance | Maintainability | Reliability | Observability
- **Description**: [What is missing or wrong]
- **Evidence**:
  > [Specific code evidence] [file:line]
  > [Additional evidence if applicable] [file:line]
- **Impact**: [What problems this causes or risks it creates]
- **Recommendation**: [High-level suggestion for addressing this gap]
- **Related**: [Links to REQ-NNNN, COMP-NNNN, or other artifact IDs if applicable]

Priority definitions:

• P0 (Critical/Blocking): Actively causing production issues, security vulnerabilities with exploit potential, data loss risks, or blocking all forward progress
• P1 (Significant): Degrades system quality, creates maintenance burden, slows development velocity, or poses moderate risk that compounds over time
• P2 (Minor/Cosmetic): Nice-to-have improvements, style inconsistencies, optimization opportunities, or long-term quality investments

Assign GAP-NNNN IDs: Sort all gaps alphabetically by title (case-insensitive), then assign sequential four-digit numbers starting at 0001.

Step 4: Build Risk Registry

For each identified risk (potential future problem, not a current gap), create a structured entry.

Risk format:

### RISK-0001: [Title]
- **Severity**: Critical | High | Medium | Low
- **Likelihood**: Almost Certain | Likely | Possible | Unlikely | Rare
- **Priority**: P0 | P1 | P2 (derived from Severity x Likelihood)
- **Category**: Architecture | Security | Performance | Maintainability | Reliability | Operational
- **Description**: [What could go wrong]
- **Evidence**:
  > [Code evidence showing why this risk exists] [file:line]
- **Trigger Conditions**: [What would cause this risk to materialize]
- **Impact**: [Consequences if the risk materializes]
- **Mitigation**: [Recommended actions to reduce likelihood or impact]
- **Related**: [Links to GAP-NNNN, REQ-NNNN, COMP-NNNN if applicable]

Severity x Likelihood -> Priority matrix:

	Critical	High	Medium	Low
Almost Certain	P0	P0	P1	P1
Likely	P0	P1	P1	P2
Possible	P1	P1	P2	P2
Unlikely	P1	P2	P2	P2
Rare	P2	P2	P2	P2

Assign RISK-NNNN IDs: Sort all risks by severity (Critical first, then High, Medium, Low), then alphabetically by title within each severity level, then assign sequential four-digit numbers starting at 0001.

Step 5: Build Technical Debt Summary

Aggregate gaps and risks into a summary view.

1. Debt by category table:

| Category | P0 Count | P1 Count | P2 Count | Total |
|----------|----------|----------|----------|-------|
| Architecture | 2 | 5 | 3 | 10 |
| Security | 1 | 2 | 0 | 3 |
| Performance | 0 | 3 | 4 | 7 |
| Maintainability | 0 | 4 | 6 | 10 |
| Reliability | 1 | 1 | 2 | 4 |
| Observability | 0 | 1 | 3 | 4 |
| **Total** | **4** | **16** | **18** | **38** |

2. Hotspot analysis: Identify files or components that appear in multiple gaps/risks

| File/Component | Gap Count | Risk Count | Total Mentions |
|---------------|-----------|------------|----------------|
| src/routes/api.ts | 3 | 2 | 5 |
| COMP-0003 (Data Layer) | 4 | 3 | 7 |

3. Effort estimation: For each priority level, estimate aggregate remediation effort
   • P0: Immediate (days to 1 week)
   • P1: Short-term (1-4 weeks)
   • P2: Medium-term (1-3 months)

Step 6: Compile Architecture Gaps and Risks Artifact

Assemble all findings into the final artifact.

1. Write ARCH_GAPS_AND_RISKS.md following the template
2. Verify every gap and risk has [file:line] evidence
3. Cross-reference with upstream artifact IDs (COMP, REQ, ENT, INT, DEAD)
4. Validate priority assignments against the severity/likelihood matrix

Output Format

ARCH_GAPS_AND_RISKS.md Structure

# Architecture Gaps and Risks: [Project Name]

## Summary
[3-5 sentence overview: total gaps found, total risks, critical items count, top categories]

## Inputs
- AS_IS_SYSTEM_MODEL.md
- REVERSE_PRD.md
- Codebase at: [path]

## Outputs
- ARCH_GAPS_AND_RISKS.md (this document)

## Assumptions
- [ASM-NNNN]: [Assumption with rationale]

## Open Questions
- [OQ-NNNN]: [Question about areas that could not be fully assessed]

## Main Content

### Gap Inventory

#### Critical (P0)
[GAP-NNNN entries with Priority P0]

#### Significant (P1)
[GAP-NNNN entries with Priority P1]

#### Minor (P2)
[GAP-NNNN entries with Priority P2]

### Risk Registry

#### Critical Severity
[RISK-NNNN entries with Severity Critical]

#### High Severity
[RISK-NNNN entries with Severity High]

#### Medium Severity
[RISK-NNNN entries with Severity Medium]

#### Low Severity
[RISK-NNNN entries with Severity Low]

### Technical Debt Summary

#### Debt by Category
| Category | P0 | P1 | P2 | Total |
|----------|----|----|----|----|

#### Hotspot Analysis
| File/Component | Gap Count | Risk Count | Total |
|---------------|-----------|------------|-------|

#### Effort Estimation
| Priority | Count | Estimated Effort | Recommended Timeline |
|----------|-------|-----------------|---------------------|

### Gap-Risk Cross Reference
| Gap ID | Related Risks | Category | Priority |
|--------|--------------|----------|----------|

### Traceability
| ID | Type | Related COMP | Related REQ | Related ENT | Related INT |
|----|------|-------------|-------------|-------------|-------------|

## Acceptance Criteria
- [ ] Every GAP-NNNN cites [file:line] evidence
- [ ] Every RISK-NNNN cites [file:line] evidence
- [ ] Priority assignments follow the severity/likelihood matrix
- [ ] Technical debt summary aggregates match individual entries
- [ ] Hotspot analysis identifies multi-gap components
- [ ] Cross-references link to upstream artifact IDs
- [ ] All categories represented in analysis (even if no findings)

Output path: artifacts/brownfield/<project_name>/ARCH_GAPS_AND_RISKS.md

Template: ${CLAUDE_PLUGIN_ROOT}/reference/templates/ARCH_GAPS_AND_RISKS.template.md

Determinism Rules

These rules ensure reproducible output regardless of when or how many times the skill is invoked on the same inputs.

1. GAP-NNNN IDs: Sort all gaps alphabetically by title (case-insensitive), then assign sequential four-digit numbers starting at 0001
2. RISK-NNNN IDs: Sort all risks by severity (Critical > High > Medium > Low), then alphabetically by title within each severity level, then assign sequential four-digit numbers starting at 0001
3. Gap sections: Group by priority (P0 first, then P1, then P2)
4. Risk sections: Group by severity (Critical first, then High, Medium, Low)
5. Technical debt table rows: Sort by Category alphabetically
6. Hotspot rows: Sort by Total Mentions descending, then by File/Component alphabetically
7. Sections: Always in template order, never reordered
8. No timestamps: Do not include generation timestamps in artifact body
9. Cross-reference table: Sort by ID numerically
10. Traceability table: Sort by ID (GAP first, then RISK), numerically within each type

Evidence Citation Rules

Every gap and risk MUST include evidence citations from actual code.

Format: > Claim text [relative/path/to/file.ext:line_number]

Examples:

> Database password is hardcoded as string literal [src/config/db.ts:12]
> SQL query constructed via string concatenation without parameterization [src/repositories/user.ts:34]
> No rate limiting middleware applied to authentication endpoints [src/routes/auth.ts:5-20]
> Error handler returns stack traces to client in all environments [src/middleware/error.ts:18]
> Component imports 15 other modules creating high fan-out coupling [src/services/order.ts:1-15]

Rules:

• Single line reference: [file:line]
• Range reference: [file:start-end]
• Multiple files: [file1:line] [file2:line]
• Aggregate claims (e.g., "no tests exist") should cite the directory expected to contain tests
• If a gap is structural (e.g., "missing middleware"), cite the file where the middleware SHOULD be but is not
• NEVER create a gap without at least one code evidence citation

Quality Checklist

Before finalizing the artifact, verify:

• Every GAP-NNNN has at least one [file:line] evidence citation
• Every RISK-NNNN has at least one [file:line] evidence citation
• P0 gaps genuinely represent critical/blocking issues
• Risk priority correctly derives from severity x likelihood matrix
• Technical debt summary counts match the actual number of GAP/RISK entries
• Hotspot analysis correctly identifies most-mentioned files/components
• All six categories analyzed: Architecture, Security, Performance, Maintainability, Reliability, Observability
• Dead code from REVERSE_PRD.md addressed (either as gap or acknowledged)
• Cross-references to upstream COMP, REQ, ENT, INT IDs are valid
• GAP-NNNN IDs sorted alphabetically by title
• RISK-NNNN IDs sorted by severity then alphabetically by title
• No duplicate gaps (same issue described differently)
• Recommendations are actionable and specific

Error Handling

• AS_IS_SYSTEM_MODEL.md not found: Report error; direct user to run codebase-discovery-as-is first
• REVERSE_PRD.md not found: Report error; direct user to run reverse-prd first
• No gaps found: Document that analysis was performed but no gaps detected; this is a valid (though unusual) outcome. Still check all six categories.
• Codebase changed since upstream artifacts: Note in Assumptions that analysis is based on a point-in-time snapshot; recommend re-running upstream skills if significant changes occurred
• Cannot assess certain categories: Document what was attempted and why assessment failed in Open Questions (e.g., "Cannot assess performance without load test data")