---
name: "spectre-architecture_review"
description: "👻 | Conduct principal architecture review"
user-invocable: true
---

# architecture_review

## Input Handling

Treat the current command arguments as this workflow's input. When invoked from a slash command, use the forwarded `$ARGUMENTS` value.


# architecture_review: Technical review of completed features

## Description
- **What** — Principal systems architect review focusing on compounding decisions: architectural debt, missed abstractions, performance cliffs, unnecessary complexity
- **Outcome** — Architecture review report with actionable findings organized by severity and type

## Variables

### Dynamic Variables
- `feature_description`: Feature being reviewed — (via ARGUMENTS). If
- `paths_or_files`: Relevant paths to examine — (via ARGUMENTS)
- `arch_notes_or_docs`: Existing architecture context — (via ARGUMENTS, optional)

### ARGUMENTS Input

<ARGUMENTS>
$ARGUMENTS
</ARGUMENTS>

## Instructions

**Review Philosophy** (cross-cutting guidelines):
- **Compounding matters**: Focus on what gets harder to change later, not what's easy to fix now
- **Simplicity is a feature**: The best code is often less code, fewer abstractions, fewer moving parts
- **Context is king**: A "bad" pattern in isolation might be the right choice given project constraints
- **Be specific**: Vague feedback like "could be more modular" is useless. Point to exact files, functions, and concrete alternatives

**Constraints**:
- Don't suggest changes that would take longer to implement than the feature itself unless they're critical
- Don't recommend adding abstractions "for future flexibility" unless there's concrete evidence we'll need them
- If you don't have concerns in a section, say "No concerns" and move on—don't manufacture feedback
- Be direct. "This is fine" is a valid assessment.

**Adapt**
- If ARGUMENTS is empty, gather the review scope from the current thread context.
- If the current thread context is also ambigious, ask the user to clarify the scope of the review.

## Step (1/3) - Review Existing Architecture Documents
- **Action** - ReviewArchitecture: Find and review existing architecture documents
  - search for docs/architecture.md and read it if it exists
  - if not, continue and use general architectural best practices during review

## Step (1/2) - Explore Implementation

- **Action** — ExploreCode: Thoroughly examine the implementation
  - Read the code at `paths_or_files`
  - Understand the data flow
  - Trace the dependencies
  - Review `arch_notes_or_docs` if provided
  - **If**: Paths unclear or missing
  - **Then**: Ask for clarification before proceeding
  - **Else**: Continue to review

## Step (2/2) - Produce Review Report

- **Action** — GenerateReview: Create structured architecture review using Report format below
  - Apply Review Philosophy guidelines throughout
  - Apply Constraints (no manufactured feedback, proportionate suggestions)
  - **If**: No concerns in a section
  - **Then**: State "No concerns" and move on
  - **Else**: Provide specific, actionable feedback

## Report

**Output Format** — Architecture review with these sections:

### Executive Summary
2-3 sentences: What's the architectural story here? Is this feature setting us up well or creating future pain?

### Critical Issues (address before moving on)
Issues that will cause significant pain if left unaddressed—architectural violations, major performance problems, or patterns that will spread.

For each issue:
- **What**: The specific problem
- **Where**: Exact file(s) and line(s)
- **Why it matters**: The compounding cost over time
- **Suggested fix**: Concrete, implementable alternative

### Simplification Opportunities
Places where we're overengineering, where a simpler approach would work, or where we've introduced abstractions we don't yet need.

### Architecture Alignment
- Does this follow existing project patterns, or introduce new ones?
- If new patterns: Are they intentional improvements or accidental divergence?
- Are there existing utilities/patterns in the codebase this should have used?

### Future-Proofing Considerations
- What assumptions is this code making that might not hold?
- If this feature grows 10x in usage/complexity, what breaks first?
- Are there integration points that need better contracts/interfaces?

### Performance Notes
Only mention performance if there's a clear problem or a clear win—don't speculate about micro-optimizations.

### What's Done Well
Briefly note architectural choices worth preserving or patterns worth spreading to other parts of the codebase.

## Success Criteria

**Step 1 - Explore Implementation**:
- [ ] All specified paths/files read and understood
- [ ] Data flow traced through implementation
- [ ] Dependencies identified and examined
- [ ] Architecture context reviewed if provided

**Step 2 - Produce Review Report**:
- [ ] Executive Summary provides clear architectural assessment (2-3 sentences)
- [ ] Critical Issues include What/Where/Why/Suggested fix for each
- [ ] Simplification Opportunities identify overengineering (or "No concerns")
- [ ] Architecture Alignment addresses pattern consistency
- [ ] Future-Proofing identifies assumptions and scaling concerns
- [ ] Performance Notes only included if clear problem/win exists
- [ ] What's Done Well acknowledges good patterns
- [ ] All feedback is specific with exact files/lines
- [ ] No manufactured feedback—"No concerns" used when appropriate
- [ ] Suggestions proportionate to feature scope