architecture-research

# Architecture Research

Understand how real systems work before committing to a technical direction.
Produce a decision artifact backed by inspectable evidence, not a feature table,
vendor narrative, or speculative target architecture.

Read both references before completing decision-grade work:

- [Architecture lenses](references/architecture-lenses.md) explains how to
  inspect ownership, authority, wiring, lifecycle, recovery, trade-offs, and
  adoption risk.
- [Evidence matrix and decision template](references/evidence-matrix.md)
  provides the output structure.

## Operating Contract

- Direct actions: read-only discovery, source inspection, local experiments,
  decision recovery, comparison, and drafting within the requested access path.
- Escalate before: paid API use, new accounts or legal terms, publication of
  non-public findings, remote mutations, or an unauthorized production choice.
- Evidence-backed pushback: challenge category errors, unsupported architecture
  claims, false equivalence, and premature hyperscale design with cited facts.
- Feedback loop: test decisive claims, record unknowns and reversal evidence,
  then re-open the decision when its review trigger fires.

### Scope and handoff

Use this skill for four related tasks:

- **Landscape research**: identify and compare relevant systems or approaches.
- **System archaeology**: reconstruct how a system actually works from source,
  deployment material, tests, runtime evidence, and authoritative documents.
- **Architecture decision**: choose whether to adopt, adapt, build, defer, or
  retain the current system.
- **Decision reassessment**: recover an earlier decision, check whether its
  assumptions still hold, and keep or revise it using current evidence.

This skill owns external research, evidence, comparison, and the decision
boundary. Once a direction is selected, hand detailed internal boundaries,
contracts, and target architecture to `architecture-foundation`. Use
`product-discovery` for customer or market validation without a technical
decision question.

Respect the requested access path and repository instructions. Never expose
credentials or reproduce private implementation details in a public artifact.

Do not invoke this workflow for a small bug fix, rename, formatting change,
routine dependency use, or when the foundational technology is explicitly fixed
by the user or nearest repository instructions.

## Workflow

### 1. State the decision question

Before searching, write a compact research brief:

- User outcome and the exact capability the system must own.
- Current boundary, missing layer, and the decision to make.
- One or more representative quality scenarios: stimulus, operating condition,
  expected response, and measurable success.
- Constraints that matter now: scale horizon, freshness, latency, quality,
  privacy, deployment, budget, licensing, data ownership, and team capacity.
- Explicit non-goals and the cost of making no change.

Scale research depth to decision risk. Reversible component choices need less
evidence than a new source of truth, data platform, hosted dependency, or
one-way migration.

Challenge category errors early. A browser, API wrapper, scraper, search index,
agent runtime, and answer engine can share a surface while owning different
capabilities.

### 2. Recover existing context without inheriting its claims

When prior decisions, incidents, chats, ADRs, or benchmarks exist, extract:

- The decision and alternatives considered at the time.
- Assumptions, constraints, unresolved unknowns, and promised validation.
- What was actually implemented and what happened in operation.
- Which facts are stale, contradicted, or were never verified.

Prefer focused summaries, exact excerpts, decision records, and runtime
artifacts over loading whole conversation archives. Treat prior conclusions as
leads until their evidence is re-opened.

### 3. Select representative alternatives

Search before proposing architecture. Include only alternatives that can change
the decision:

- Maintained open-source systems with inspectable source and deployment paths.
- Commercial systems with authoritative technical material.
- Standards, public datasets, protocols, and lower-level reusable components.
- The current system and the option to make no change.

Classify each candidate as direct, adjacent, component, or non-comparable.
Do not pad the comparison to reach an arbitrary count. Decide the possible
reuse unit: whole system, subsystem, component, protocol, data model, or pattern.

### 4. Build an evidence ledger

Prefer primary evidence in this order:

1. Source code, tests, manifests, schemas, releases, and reproducible runtime
   behavior.
2. Official technical documentation, papers, standards, patents, and
   engineering posts.
3. Official product, license, and pricing material for product-level claims.
4. Independent measurements whose method, date, and environment are visible.

For current products, dependencies, pricing, licenses, or architecture, browse
and record the date or revision. Use secondary sources only to locate primary
evidence or to add clearly attributed independent evaluation.

Tag every decision-relevant claim:

- **Verified**: directly supported by cited code, documentation, or measurement.
- **Inferred**: supported by evidence but not stated directly; include the
  reasoning and confidence.
- **Unknown**: not revealed by available evidence; say what would resolve it.

Preserve contradictions. A public SDK, plugin, or MCP server proves an interface
exists; it does not prove that the underlying data, model, index, scheduler, or
hosted control plane is open or independently reproducible.

### 5. Trace the real system

Apply the relevant lenses from
[architecture-lenses.md](references/architecture-lenses.md). At minimum answer:

- What is the end-to-end path from input to user-visible result?
- Who owns each data, control, and operational boundary?
- What is authorit