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

name	description
architecture-research	Optional pre-work for investigating technical landscape, existing system constraints, and comparable architectures before the strict Architect pipeline begins. This skill produces internal analysis only — no file artifacts. Research may only compile constraints, options, and trade-offs — it MUST NOT make final architecture decisions.

This is optional pre-work, not part of the strict Architect pipeline. It is invoked before analyze-prd when the PRD involves significant technical constraints that benefit from landscape understanding.

Important

This skill produces internal analysis only. It MUST NOT write any file artifacts. The strict pipeline output is docs/architecture/{feature}.md only.

Boundary: Research vs Design

This skill is strictly research. It may only:

• Compile constraints: Document existing system constraints, service boundaries, data flow, technology stack, integration dependencies, SLAs, and compliance requirements
• Catalog options: List available technology options, architecture patterns, and integration approaches with their trade-offs
• Surface trade-offs: Present pros, cons, and trade-offs of candidate approaches without making a final selection
• Identify risks: Flag technical risks, unknowns, and potential blockers

This skill MUST NOT:

• Make final architecture decisions (those belong exclusively to design-architecture)
• Select a technology stack (that is a final decision)
• Define service boundaries (that is a final decision)
• Define API contracts, data models, or database schemas (those are final decisions)
• Write ADRs (those are final decisions)
• Recommend a single approach over others without presenting alternatives (that is a disguised final decision)
• Produce any architecture document or artifact

The boundary is simple: research compiles what is possible; design decides what we build. If the output reads like a decision rather than a list of options, it has crossed the boundary into design-architecture territory.

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 make final architecture decisions of any kind
• Do not reverse-engineer competitor internal implementation details
• Do not write code, schemas, or API definitions
• Do not break down tasks or create milestones
• Do not produce file artifacts

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. Retain findings as internal analysis to inform analyze-prd and design-architecture

Output

This skill produces internal analysis only. Findings are carried forward in memory to inform the next pipeline steps. No file is written.

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
• Present options with trade-offs, not recommendations with conclusions
• All final architecture decisions must appear in docs/architecture/{feature}.md produced by design-architecture