igor1309/arch-spec-review

Architecture Specification Review

Review architecture specifications at the appropriate level of abstraction, evaluating whether they successfully define system structure without drifting into implementation details.

Document Classification

Architecture specifications exist on a spectrum:

Top-level Architecture Specs (this skill's focus):

• Define WHO does WHAT
• Establish boundaries and responsibilities
• Describe flows and coordination patterns
• State architectural constraints and guarantees
• Identify extension points
• Implementation-agnostic

Executable Specifications:

• Define precise behavior and semantics
• Include comprehensive test scenarios
• Specify input/output contracts exactly
• More detailed, but still technology-neutral

Implementation Documentation:

• Describes HOW components work internally
• Names specific data structures, algorithms, protocols
• Technology and framework specific

Review Process

1. Understand Document Intent

Before reviewing, read the document's stated goals:

• What level of abstraction does it target?
• What scope boundaries are declared?
• What's explicitly deferred or out of scope?

Never review against your expectations - review against the document's stated purpose.

2. Evaluate Completeness

For architecture specifications, assess whether these are clear:

Boundaries: Is each component's responsibility distinct and well-defined?

• Can you explain what each component does without talking about how?
• Are there clear lines between components?

Flows: Are the key scenarios described?

• Bootstrap/initialization
• Primary operational paths
• Update/refresh mechanisms
• Error handling boundaries

Constraints: Are architectural guarantees stated?

• Synchronicity/asynchronicity
• Atomicity and consistency
• Immutability
• Failure modes

Extension Points: Can the design evolve?

• What can be swapped without ripple effects?
• Where is flexibility preserved?

Deferred Decisions: What's appropriately left for later?

• Are open items acknowledged explicitly?
• Is deferral justified (team decision needed, product semantics unclear)?

3. Check Abstraction Discipline

Architecture specs should NOT specify:

• Internal data structures ("uses a Dictionary keyed by...")
• Algorithms or specific mechanisms ("uses copy-on-write...")
• Serialization formats or protocols (unless that IS the architecture)
• Specific technologies or frameworks
• Implementation-level error types

Architecture specs SHOULD specify:

• Responsibilities ("Repository provides synchronous reads")
• Guarantees ("atomic swap - readers see old or new, never partial")
• Boundaries ("Orchestrator never handles domain queries")
• Constraints ("immutable snapshots")
• Coordination patterns ("Orchestrator loads, processes, then swaps")

4. Self-Evaluate Before Presenting

Critical pause: Before sharing your review, evaluate your own findings.

Ask yourself:

• Am I asking about HOW when the doc only promises WHO and WHAT?

  • Bad: "What data structure does the Repository use?"
  • Good: "What guarantees does the Repository provide to readers during updates?"

• Would my questions add clarity or just detail noise?

  • If the answer doesn't affect architectural boundaries, it's probably implementation detail.

• Am I respecting explicit scope boundaries?

  • If the doc says "duplicates policy is TBD," don't demand a resolution.
  • If the doc says "implementation-agnostic," don't ask about specific technologies.

• Could I explain why the architecture needs to specify this?

  • If you can't articulate the architectural impact, question your question.

Change your perspective:

• Read as the author: Are you demanding details they intentionally abstracted?
• Read as an implementer: Do your questions help understand the structure, or just satisfy curiosity about mechanics?
• Read as a future maintainer: Would knowing this detail help understand the design decisions and trade-offs?

5. Present Findings

Structure your review:

What Works:

• Acknowledge clear boundaries, well-defined flows, explicit constraints
• Recognize appropriate deferrals and scope discipline

Questions (only architectural concerns):

• Ambiguities in responsibilities or guarantees
• Missing flows or undefined coordination
• Unclear extension points
• Contradictions or gaps in constraints

Not: "How does X work internally?" But: "What guarantee does X provide to its clients?"

Avoid:

• Premature optimization suggestions
• Implementation recommendations
• Technology preferences
• Asking about appropriately deferred decisions

Anti-Patterns to Avoid

Over-Specification Demands:

• Asking for internal mechanisms when boundaries are clear
• Requesting concrete examples that could become templates
• Pushing for decisions the document explicitly defers

Scope Creep:

• Suggesting features beyond the stated scope
• Reviewing against a different abstraction level than targeted
• Conflating "architecture" with "implementation"

Pattern Matching:

• Expecting specific section structures
• Demanding your preferred architectural style
• Checking against a mental template rather than reading what's there

Success Criteria

A good architecture specification:

• ✅ Clearly separates concerns
• ✅ Defines responsibilities without dictating mechanisms
• ✅ Describes flows at the right level
• ✅ States constraints and guarantees explicitly
• ✅ Identifies extension points
• ✅ Acknowledges deferred decisions appropriately

A good review:

• ✅ Evaluates against the document's stated goals
• ✅ Identifies genuine architectural ambiguities or gaps
• ✅ Respects abstraction boundaries
• ✅ Avoids implementation details
• ✅ Recognizes when deferral is appropriate

Common Pitfalls

For Reviewers:

• Asking "what format is the data?" when the architecture just needs to move data between components
• Demanding specific error handling mechanisms when error boundaries are clear
• Requesting implementation details about already-clear abstractions
• Forgetting that the document author made deliberate choices about what to include

For Authors:

• Over-specifying (crossing into implementation)
• Under-specifying (leaving architectural ambiguity)
• Mixing abstraction levels inconsistently
• Not explicitly acknowledging deferred decisions

Key Reminder

Architecture specs are about structure and boundaries, not implementation and mechanisms.

When in doubt, ask: "Does this question change how components interact, or just how a component works internally?"