/architecture-research

name: architecture-research
description: "Evidence-driven architecture research for understanding real systems and making technical decisions. Use when doing architecture landscape studies, source-backed system archaeology, build-vs-buy or adopt/adapt/build decisions, open-source and commercial comparisons, revisiting an earlier architecture choice, or handling requests such as 架构调研, 架构选型, 竞品架构, 技术尽调, 同类方案, 开源替代, how is X built, and what should we learn from X. Do not use for small mechanical changes, market-only discovery, or detailed design after the technology direction is already fixed."

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

re