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 explains how to inspect ownership, authority, wiring, lifecycle, recovery, trade-offs, and adoption risk.
• Evidence matrix and decision template 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. 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 authoritative, what is derived, and what is only ephemeral?
• What survives restart, and how are stale or divergent states reconciled?
• Is each claimed capability merely declared, actually implemented, wired into the live path, exercised, and measured?
• Which decisions are sensitivity or trade-off points for the named scenarios?

Inspect open-source implementation, tests, releases, and self-host deployment, not only the README. For closed systems, draw a visible boundary around the public surface and keep the hidden core unknown.