looply-architecture-review

name	looply-architecture-review
description	Use to review architecture and design independently. Identifies structural improvements, validates against existing ADRs, and verifies compliance with codebase design principles.

Use this skill when the user explicitly invokes $looply-architecture-review, asks to run /looply:architecture-review, or when architecture assessment is needed standalone. Workflow phase: delivery. Primary orchestrator: architect.

Quick usage:

• $looply-architecture-review <feature-name> "[scope-reference]" "[focus-areas...]"

Primary references:

• Workflow playbook: ../../../../.looply/state/workflow-playbook.opencode.md
• Host status contract: ../../../../.looply/state/host-status-contract.json
• Managed pack: ../../../../.looply/managed/packs/software-delivery-suite
• Custom overrides: ../../../../.looply/custom
• Execution hints: ../../../../.looply/state/execution-hints.opencode.json
• Context index: ../../../../.looply/state/context-index.md
• Project context: ../../../../.looply/custom/project-context.md
• Session context: ../../../../.looply/custom/session-context.md
• Knowledge graph: ../../../../.looply/state/knowledge-graph.json

Usage:

• Explicit mention: $looply-architecture-review
• Workflow alias to honor: /looply:architecture-review
• Syntax in Codex: $looply-architecture-review <feature-name> "[scope-reference]" "[focus-areas...]"

Example:

• $looply-architecture-review pix-webhook-retry "retry-queue-service" "evaluate eventual consistency and idempotency"

When to use:

• Design assessment before complex implementation
• Validation of adherence to existing ADRs
• Identification of structural improvements in the codebase

Curated example guidance:

• ICL mode: on
• Use examples only for style, structure and quality calibration.
• Do not copy feature-specific names, identifiers or business details from examples.
• No example was selected for this workflow.

Architecture Review Flow

Stage 1: Design Analysis

1. Load relevant artifacts: tech-spec, ADRs, knowledge-graph.json
2. Analyze the current codebase structure for the defined scope
3. Identify existing architectural patterns

Stage 2: ADR Compliance

Verify compliance with existing ADRs:

• Are documented architecture decisions respected?
• Do new decisions need their own ADR?
• Do module dependencies respect the defined direction?

Stage 3: Design Assessment

Assess the following dimensions:

Modularity:

• Well-defined responsibilities between modules?
• Is coupling between modules acceptable?
• Are interfaces between modules clear?

Scalability:

• Does the design support expected volume?
• Bottlenecks identified?
• Is the caching strategy appropriate?

Maintainability:

• Is the design easy to understand and modify?
• Are abstractions at the right level?
• Is cyclomatic complexity acceptable?

Consistency:

• Consistent patterns with the rest of the codebase?
• Does naming follow conventions?
• Is the directory structure coherent?

Stage 4: Architecture Report

Generate report in .looply/custom/features/<feature-name>/architecture-review-report.md:

# Architecture Review Report

## Scope
retry-queue-service

## ADR Compliance
- ADR-003 (Async Messaging): OK - using queue as defined
- ADR-005 (Error Handling): WARN - missing dead-letter strategy

## Assessment

### Modularity (8/10)
- Retry logic well isolated from dispatcher
- Clear interface between retry module and webhook handler

### Scalability (7/10)
- In-memory queue limits horizontal scalability
- Recommendation: migrate to external queue (Redis/SQS) when volume > 10k/s

### Maintainability (9/10)
- Clean, well-structured code
- Abstractions at the right level

### Consistency (8/10)
- Service/repository pattern maintained
- Naming follows project conventions

## Recommendations
1. Document dead-letter queue strategy (ADR)
2. Plan external queue migration in next cycle
3. Add queue size metric for observability

## Verdict
Solid design. Recommendations do not block current implementation.

Execution rules:

1. Start by reading the workflow playbook and the feature state file.
2. Run looply refresh-code-context --check before the assessment.
3. If the user asked for help, explain syntax, arguments, example, expected output and next step without mutating state.
4. Validate compliance with existing ADRs before evaluating new design.
5. Identify deviations from codebase patterns.
6. Recommendations must be actionable and prioritized.
7. Use managed pack files as canonical process definition and write local state only under .looply/custom.
8. Respond in the same language as the user's input.
9. For existing projects, use the real local codebase as the primary source of truth.
10. Follow balanced interaction mode to avoid unnecessary repeated clarifications.
11. Keep the response visually structured with clear Markdown section titles.
12. Do not use emojis.

---

Composed Agent Context

The sections below were pre-composed by looply from agent context_slots.

Constraints

• Assess compliance with existing ADRs
• Identify deviations from codebase patterns
• Recommendations must be actionable and prioritized

Escalation

• Escalate design conflicts to delivery-orchestrator
• Escalate product scope questions to pm-analyst Arguments:
• feature-name: short identifier for the feature (required)
• scope-reference: module, service or area to review (optional)
• focus-areas: optional specific areas to focus on (optional)