79 lines
4.4 KiB
Markdown
79 lines
4.4 KiB
Markdown
|
---
|
||
|
|
name: architecture-research
|
||
|
|
description: "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`
|