# Full Discovery Process for Technical Design

## Objective
Conduct a thorough, evidence-based investigation to ensure the technical design rests on verified, current, and complete information — not assumptions.

---

## Discovery Steps

### 1. Requirements Decomposition
**Extract Technical Obligations from EARS Statements**
- Parse all functional requirements to identify concrete technical needs: data models, APIs, service interfaces, business rule engines
- Extract non-functional requirements: latency targets, throughput thresholds, availability SLAs, security mandates, compliance constraints
- Identify technical constraints that are non-negotiable (regulatory, contractual, infrastructure-imposed)
- List the top three to five technical challenges that the design must solve

### 2. Existing Codebase Analysis
**Understand the Current System Before Adding to It**
- Map the overall architecture: layers, modules, service boundaries, data stores
- Identify reusable assets: services, utilities, shared libraries, data access layers
- Trace domain boundaries and existing aggregate ownership
- Document established data flow patterns and event contracts
- Determine the appropriate implementation posture: extend, refactor, wrap, or build fresh

### 3. Technology Research
**Ground Every Dependency Decision in Verified, Current Information**

Use **WebSearch** to discover:
- Established architectural patterns for this class of problem
- Industry best practices for the relevant technology stack
- Recent breaking changes, deprecations, or version incompatibilities
- Common failure modes and the solutions practitioners have adopted

Use **WebFetch** to verify:
- Official documentation for frameworks and libraries under consideration
- API reference material, authentication patterns, and usage examples
- Migration guides and known breaking changes for version upgrades
- Published performance benchmarks and comparative analyses

### 4. External Dependency Investigation
**Validate Each External Service or Library Before Committing to It**
- Retrieve official documentation and inspect the GitHub repository for activity and maintenance status
- Confirm current API signatures, authentication requirements, and data formats
- Verify version compatibility with the existing project stack
- Document rate limits, quotas, throttling behavior, and any SLA guarantees
- Identify security requirements (TLS versions, token scopes, IP allowlisting)
- Locate known issues, open bugs, or community workarounds relevant to the intended use case
- Record any gaps where deeper implementation investigation will be needed

### 5. Architecture Pattern and Boundary Analysis
**Evaluate Options Before Committing to a Direction**
- Enumerate candidate patterns relevant to the problem (examples: MVC, Clean Architecture, Hexagonal, Event-Driven, CQRS, Saga)
- Assess each pattern against: existing codebase conventions, team familiarity, scalability requirements, and operational complexity
- Identify domain ownership seams that allow parallel team implementation without merge conflicts
- Evaluate build-vs-buy trade-offs for significant components
- Select a preferred pattern; document the rationale and explicitly record rejected alternatives in `research.md`

### 6. Risk Assessment
**Surface What Could Go Wrong Before Design Is Committed**
- Performance risks: bottlenecks under expected and peak load
- Security exposure: attack surface, authentication gaps, data leakage vectors
- Integration risk: coupling, contract brittleness, dependency on external SLAs
- Technical debt implications: does this decision pay down or accumulate debt?
- Knowledge and capability gaps: skills or tooling the team does not yet have

---

## Research Guidelines

### When Research Is Always Required
- External API or service integration — verify current contracts and authentication
- Security-sensitive functionality — authenticate, authorization, data protection
- Performance-critical paths — confirm optimization approaches with benchmarks
- Dependency version changes — validate compatibility and check for breaking changes

### When Research Is Conditionally Required
- Architectural patterns for an unfamiliar problem domain
- Industry standards for specific data formats or protocols
- Compliance requirements (GDPR, HIPAA, SOC 2, PCI-DSS, etc.)
- Scalability approaches for load profiles beyond current experience

### Effective Search Strategy
1. Start with official documentation and the project's GitHub repository
2. Check release notes and changelogs for the last two versions
3. Search for blog posts and technical articles from the past six months
4. Review Stack Overflow threads for recurring integration issues
5. Examine similar open-source implementations for architectural reference

---

## Output Requirements
Capture all findings that influence design decisions in `research.md` using the shared template:

- **Summary section**: Discovery scope and the three to five most significant findings
- **Research Log**: One subsection per investigated topic with sources, findings, and design implications
- **Architecture Pattern Evaluation**: Candidate patterns with a comparison table (strengths, risks, fit)
- **Design Decisions**: Each major decision with context, alternatives considered, selected approach, rationale, and trade-offs
- **Risks and Mitigations**: One line per risk with its proposed mitigation
- **Gaps**: Items that require further investigation during implementation, explicitly labeled "Research Needed"
