opencode-workflow/skills/architecture-research/SKILL.md

name	description
architecture-research	Research technical landscape, existing system constraints, and comparable system architectures before designing architecture. This is the Architect pipeline's first step, comparable to market-research in the PM pipeline.

Use this skill when the PRD involves significant technical constraints, integration requirements, or architectural decisions that benefit from technical landscape understanding before design begins.

Goals

Use research to answer:

• What existing systems, services, and infrastructure constrain this design?
• What architectural patterns are proven in this problem domain?
• What are the technical risks and trade-offs for candidate approaches?
• What storage, scaling, and reliability decisions have been made by comparable systems?

What To Research

• Existing codebase architecture: service boundaries, data flow, communication patterns, technology stack
• System constraints: latency requirements, scale expectations, compliance requirements, existing SLAs
• Comparable system architectures: how similar problems were solved, what patterns succeeded or failed
• Technology landscape: available options for storage, messaging, compute, and their trade-offs for this use case
• Integration dependencies: upstream and downstream systems, contracts, protocols, versioning

What Not To Do

• Do not design architecture yet; this is research only
• Do not make technology selections; catalog options and trade-offs only
• Do not reverse-engineer competitor internal implementation details
• Do not produce architecture decisions or recommendations
• Do not write code, schemas, or API definitions
• Do not break down tasks or create milestones

Process

1. Read the PRD file at docs/prd/{feature}.md to understand requirements
2. Inspect the existing codebase for current architecture, service boundaries, and technology stack
3. Identify technical constraints and integration dependencies from the PRD and codebase
4. Research comparable system architectures and proven patterns for this problem domain
5. Catalog technology options with trade-offs relevant to the PRD requirements
6. Write a concise research brief

Output

Save research briefs to docs/research/{date}-{topic}-architecture.md.

This file is an input artifact for downstream Architect stages:

• analyze-prd may use it to identify architectural requirements and constraints
• design-architecture may use it to inform pattern selection and technology decisions

Use this format:

Research Question

What architectural question or constraint is being investigated?

Existing System Context

Current service boundaries, data flow, technology stack, and constraints discovered from codebase inspection.

Comparable Architectures

How similar problems have been solved, what patterns succeeded, what patterns failed, and why.

Technical Constraints

Latency, scale, compliance, integration, and infrastructure constraints that bound the design space.

Technology Options

Candidate technologies or approaches with trade-offs relevant to this use case. Present options, not decisions.

Risks And Trade-offs

Technical risks, unknowns, and trade-offs the architect must resolve during design.

Implications For Architecture

What this research means for architectural decisions the architect will make.

Sources

References, documentation, and evidence supporting the findings.

Guidance

• Prefer direct evidence from codebase inspection and documented architecture over speculation
• Prefer 3-5 proven patterns over 20 theoretical possibilities
• Call out confidence level when evidence is weak
• Tie findings back to specific PRD requirements and NFRs
• Do not make architecture decisions in this document; that belongs in design-architecture