Trade Study

Trade Studies

Trade studies capture structured comparisons when a design decision has multiple viable options. They make reasoning auditable for the team now and anyone revisiting the decision later.

When to Write One

Write one when:

• Multiple options are viable and the best choice depends on weighing competing priorities
• The decision affects downstream work (connector choice constrains PCB stackup, firmware, mechanical design)
• The decision is hard to reverse once implemented

Don't write one when:

• One option is clearly dominant
• The decision is easily reversible
• The scope is too small to justify the overhead

File Convention

Each trade study is a markdown file, dated and kebab-cased, kept in the repo (e.g. under docs/trades/):

docs/trades/YYYY-MM-DD-.md

Structure

Every trade study has exactly four sections plus a header block:

Header Block

# Trade Study: 

**Date:** YYYY-MM-DD
**Status:** OPEN | DECIDED
**Decision:**   ← only after decided

1. Context

What we're deciding and why it matters. Include:

• The problem or constraint that forced the decision
• Requirements the solution must meet (quantified where possible)
• Use cases affected by the decision

2. Options

Each viable approach as a subsection (### Option A: ...). Describe concisely — what the approach is, how it works, key characteristics. No advocacy — just facts.

3. Comparison Table

Rows are evaluation criteria, columns are options. Use qualitative ratings with explanation, not bare checkmarks.

| Criteria | A:  | B:  |
|---|---|---|
| **** |  |  |

Good criteria to consider for hardware decisions:

• JLCPCB/LCSC availability and stock
• Board space impact (mm² estimate)
• Component count / BOM cost
• ADC channels, MCU peripherals consumed
• New packages required (ato create part)
• Accuracy / precision at operating conditions
• Temperature drift behavior
• Failure modes and detectability
• Firmware complexity
• Reusability across other designs
• Power sequencing / hot-swap implications
• Mechanical constraints (PCB thickness, connector alignment)

Not all criteria apply to every decision — pick the ones that differentiate the options.

4. Recommendation

Which option and why, structured as:

• Rationale: why the chosen option wins on the criteria that matter most for this specific use case
• What we're giving up: explicitly acknowledge the trade-offs accepted
• When to revisit: conditions under which the decision should be reconsidered

Optional: Research Findings

If research uncovered facts that eliminated options or changed the landscape, add a ## Research Findings section between Comparison and Recommendation. This is for discovered constraints (e.g., "no 0.8mm card-edge power connectors exist on LCSC"), not for general background.

After a Decision

Update the header:

• Change **Status:** from OPEN to DECIDED
• Add **Decision:** line with one-line summary
• Keep the full trade study in the repo as a record — don't delete it

Workflow

1. Research options before writing — check datasheets, LCSC/JLCPCB availability, existing packages, and the atopile registry
2. Draft all four sections. Get the comparison table right — this is the core value
3. Review with the user before marking DECIDED (trade studies with Status: OPEN are proposals)
4. Decide — update status, add decision line
5. Reference the trade study from relevant design docs so future readers can find the reasoning

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mawildoer
• Source: mawildoer/atopile-agent-skill
• License: MIT

Install and usage instructions live in the source repository linked above.