Technical Spec Reviewing

Technical Spec Reviewing

Purpose

Systematically review technical specifications to ensure they are complete, feasible, secure, and ready for implementation. Catches architectural issues, security gaps, and operational blind spots before engineering work begins.

When NOT to Use This Skill

• Creating technical specs (use technical-spec-writing instead)
• Reviewing PRDs (use prd-reviewing instead)
• Reviewing feature specs (use feature-spec-reviewing instead)
• Code review (different domain)
• No spec exists yet (nothing to review)

Review Workflow

Step 1: Document Assessment

Read the entire technical spec and assess completeness:

Initial Assessment:
- [ ] System overview explains the approach
- [ ] Component architecture is defined
- [ ] APIs are fully specified
- [ ] Data model is documented
- [ ] Performance targets exist
- [ ] Security considerations addressed
- [ ] Migration plan included

Red Flags:

• No rationale for design decisions
• Missing component responsibilities
• APIs without error responses
• No performance targets
• Security as afterthought
• No rollback plan

Step 2: System Overview Review

Evaluate the problem and solution framing:

System Overview Checklist:
1. Is the problem statement clear?
2. Does the solution address the problem?
3. Are design decisions justified with rationale?
4. Is the scope clearly bounded?
5. Are out-of-scope items documented?
6. Does it align with requirements (PRD/Feature Spec)?

Severity Guide:

Step 3: Architecture Review

Evaluate the component architecture:

Architecture Checklist:
- [ ] Components have clear responsibilities
- [ ] Component boundaries are well-defined
- [ ] Dependencies are documented
- [ ] Data flow is clear
- [ ] Coupling is appropriate
- [ ] Scalability is considered
- [ ] Failure modes identified

Architecture Questions:

Step 4: API Design Review

Evaluate API completeness and quality:

API Review Checklist:
- [ ] All endpoints documented
- [ ] Request/response schemas complete
- [ ] Error responses specified
- [ ] Authentication/authorization defined
- [ ] Rate limiting documented
- [ ] Versioning strategy clear
- [ ] Idempotency addressed (for mutations)

API Quality Tests:

Step 5: Data Model Review

Evaluate data design:

Data Model Checklist:
- [ ] All entities defined
- [ ] Relationships documented
- [ ] Indexes specified
- [ ] Constraints defined
- [ ] Migration scripts included
- [ ] Data lifecycle addressed
- [ ] Backup/recovery considered

Data Model Questions:

Step 6: Performance Review

Evaluate performance planning:

Performance Checklist:
- [ ] Latency targets defined (p50, p95, p99)
- [ ] Throughput targets specified
- [ ] Caching strategy documented
- [ ] Database query optimization planned
- [ ] Async processing identified
- [ ] Load testing approach

Performance Quality:

Step 7: Security Review

Evaluate security considerations:

Security Checklist:
- [ ] Authentication mechanism defined
- [ ] Authorization model specified
- [ ] Data protection (at rest, in transit)
- [ ] Input validation strategy
- [ ] OWASP Top 10 addressed
- [ ] Audit logging planned
- [ ] Secrets management

Security Red Flags:

Step 8: Operational Readiness

Evaluate operational concerns:

Operations Checklist:
- [ ] Logging strategy defined
- [ ] Metrics identified
- [ ] Alerting thresholds set
- [ ] Health checks specified
- [ ] Deployment strategy clear
- [ ] Rollback plan documented
- [ ] Feature flags defined
- [ ] On-call runbook items

Operational Maturity:

Step 9: Migration & Rollout Review

Evaluate deployment planning:

Migration Checklist:
- [ ] Migration steps defined
- [ ] Each step is reversible
- [ ] Data migration addressed
- [ ] Feature flags for gradual rollout
- [ ] Rollback triggers defined
- [ ] Rollout phases planned
- [ ] Success criteria per phase

Migration Questions:

Step 10: Generate Review Report

Compile findings using the template below.

Severity Levels

Severity Examples

BLOCKER:

• No security section
• Missing authentication design
• No error handling defined
• Data model fundamentally flawed
• No rollback possible

CRITICAL:

• Performance targets missing
• Incomplete API error responses
• No rate limiting
• Missing migration plan
• Security gaps (e.g., no input validation)

MAJOR:

• Vague component responsibilities
• Missing non-functional requirements
• Incomplete observability plan
• No feature flags for rollout
• Missing capacity planning

MINOR:

• Minor documentation gaps
• Additional edge cases nice to have
• Could add more examples
• Formatting inconsistencies

Review Report Template

# Technical Spec Review: [System/Feature Name]

**Reviewer:** [Name]
**Review Date:** [Date]
**Spec Version:** [Version]
**Spec Author:** [Name]

---

## Summary

**Status:** [APPROVE / APPROVE WITH CHANGES / NEEDS REVISION / MAJOR REVISION]

**Implementation Readiness:** [Ready / Ready After Fixes / Not Ready]

**Assessment:**
[2-3 sentences on overall quality and readiness]

---

## Findings by Severity

### Blockers
- [ ] [Finding with location and recommendation]

### Critical
- [ ] [Finding with location and recommendation]

### Major
- [ ] [Finding with location and recommendation]

### Minor
- [ ] [Finding with location and recommendation]

---

## Section Ratings

| Section | Rating | Notes |
|---------|--------|-------|
| System Overview | [Strong/Adequate/Weak/Missing] | |
| Architecture | [Strong/Adequate/Weak/Missing] | |
| API Design | [Strong/Adequate/Weak/Missing] | |
| Data Model | [Strong/Adequate/Weak/Missing] | |
| Performance | [Strong/Adequate/Weak/Missing] | |
| Security | [Strong/Adequate/Weak/Missing] | |
| Operations | [Strong/Adequate/Weak/Missing] | |
| Migration | [Strong/Adequate/Weak/Missing] | |

---

## Architecture Assessment

**Scalability:** [Good / Concerns / Not Addressed]
- [Notes]

**Reliability:** [Good / Concerns / Not Addressed]
- [Notes]

**Maintainability:** [Good / Concerns / Not Addressed]
- [Notes]

---

## Security Assessment

□ Authentication - [Adequate/Gaps/Missing]
□ Authorization - [Adequate/Gaps/Missing]
□ Data Protection - [Adequate/Gaps/Missing]
□ Input Validation - [Adequate/Gaps/Missing]
□ OWASP Top 10 - [Addressed/Gaps/Missing]

**Security Score:** [X/5]

---

## Operational Readiness

□ Logging - [Defined/Partial/Missing]
□ Metrics - [Defined/Partial/Missing]
□ Alerting - [Defined/Partial/Missing]
□ Deployment - [Defined/Partial/Missing]
□ Rollback - [Defined/Partial/Missing]

**Operations Score:** [X/5]

---

## Strengths
- [What the spec does well]
- [What the spec does well]

## Risks
1. [Risk and suggested mitigation]
2. [Risk and suggested mitigation]

---

## Questions for Author
1. [Clarifying question]
2. [Clarifying question]

---

## Recommendation

[Detailed recommendation with specific next steps]

Examples

Example 1: Strong Spec (Minor Feedback)

Status: APPROVE WITH CHANGES

Assessment: Well-designed system with clear architecture and comprehensive API documentation. Minor gaps in observability and could benefit from more detailed rollback procedures.

Findings:

• MINOR: Missing p99 latency targets
• MINOR: Alerting thresholds not defined
• MINOR: Add example for error recovery flow

Section Ratings:

Example 2: Needs Work (Critical Gaps)

Status: NEEDS REVISION

Assessment: Good system overview but significant gaps in security and operational planning. Error handling incomplete. Recommend addressing security concerns before implementation begins.

Findings:

• CRITICAL: No rate limiting defined
• CRITICAL: Input validation strategy missing
• CRITICAL: No rollback plan for database migration
• MAJOR: Missing circuit breaker for external dependencies
• MAJOR: No feature flags for gradual rollout
• MAJOR: Alerting strategy undefined

Security Score: 2/5 Operations Score: 1/5

Example 3: Major Problems

Status: MAJOR REVISION REQUIRED

Assessment: Architecture has fundamental issues - single point of failure in message queue, no data consistency strategy for distributed writes. Recommend architectural review session.

Findings:

• BLOCKER: No authentication for internal service communication
• BLOCKER: Single message queue with no failover
• BLOCKER: Distributed transaction across 3 services without saga pattern
• CRITICAL: No data backup strategy
• CRITICAL: Missing capacity planning

Recommendation: Schedule architecture review meeting. Consider:

1. Add service mesh for internal auth
2. Implement message queue clustering
3. Design saga pattern for distributed transactions

Review Focus Areas by Spec Type

New Service

Focus on: Architecture, scalability, operational readiness, security

New API

Focus on: API design, authentication, rate limiting, documentation

Database Changes

Focus on: Data model, migrations, backward compatibility, performance

Performance Optimization

Focus on: Targets, measurement, caching, async processing

Security Enhancement

Focus on: Threat model, authentication, authorization, encryption

Integration with Other Skills

Reviews Output From:

• technical-spec-writing - Validate completed technical specs

Works With:

• feature-spec-reviewing - Review associated feature specs
• prd-reviewing - Verify alignment with product requirements

Leads To:

• sparc-planning - After spec approved, plan implementation

Resources

• See CHECKLIST.md for comprehensive review checklist

Related Agent

For comprehensive specification guidance that coordinates this and other spec skills, use the specification-architect agent.