---
allowed-tools: Read, Bash(mantle *)
---

Define the system design by thinking from first principles -- decompose the
product into its irreducible building blocks, then assemble them into a system
using the research already gathered. Start with what must be true for the product
to work, not with frameworks or patterns.

Be collaborative, precise, and Socratic. Ask probing questions. Surface the real
constraints. Challenge inherited conventions. The user makes the final calls.

## Step 1 — Check prerequisites

Check whether `.mantle/`, `.mantle/state.md`, and `.mantle/product-design.md`
exist by reading them.

- If `.mantle/` does not exist, tell them to run `mantle init` first.
- If `product-design.md` does not exist, tell them to run `/mantle:design-product`
  first.
- Read `state.md` and verify status is `product-design`. If not, tell them the
  current status and what step to run next.

## Step 2 — Load context

Read and internalise:
- `.mantle/idea.md` — the core problem and insight
- `.mantle/product-design.md` — the product definition
- Any files in `.mantle/challenges/` — stress-test results
- Any files in `.mantle/research/` — research findings on available tools,
  libraries, patterns, and prior art

The product design defines the constraints. The research provides the inventory
of available building blocks. This session decides how to assemble them.

If no research exists, tell the user:

> Before designing the system, you should research what building blocks are
> available — existing libraries, tools, protocols, and patterns that could be
> used or adapted. Do that research first, then come back here.

You may proceed without research if the user explicitly chooses to, but note that
decisions made without research carry lower confidence.

## Analysis scratchpad

Before synthesising context, evaluating design trade-offs, or making
architecture recommendations, use `<analysis>` blocks to organise your
thinking. These blocks are internal scratchpad — do NOT show them to the user.
Strip them from any saved output.

```
<analysis>
- What are the real constraints vs inherited conventions?
- Does the research actually support this technology choice?
- Which building block is riskiest and should be spiked first?
- Where am I making assumptions the research didn't cover?
</analysis>
```

Use `<analysis>` whenever you need to weigh competing evidence or draft a
synthesis before presenting it.

## Step 3 — Interactive system design session

This is a collaborative conversation, not a monologue. Work through the following
phases one at a time, asking questions and making recommendations. Do NOT dump
everything at once.

### Phase A — Identify the true constraints

Start here. Before any architecture or technology discussion, extract the
non-negotiable constraints from the product design:

- What must be true for this product to work at all?
- What are the real constraints — performance, latency, data volume, user
  concurrency, deployment environment, budget?
- Which constraints come from the problem itself vs inherited convention?
- What can we ignore? What "obvious requirements" are actually optional?

Strip away assumptions. Name each constraint explicitly and classify it:
**hard** (violating it means the product doesn't work) or
**soft** (violating it degrades quality but doesn't break it).

### Phase B — Decompose into building blocks

With constraints established, decompose the product into its fundamental pieces.
Not "components" in the architecture-pattern sense — the irreducible capabilities
the system must have.

For each building block, answer:
1. **What does it do?** — one sentence, no jargon
2. **What correctness means** — what invariants must hold?
3. **What it depends on** — inputs, preconditions, other blocks
4. **What depends on it** — who consumes its output?

These building blocks are the atoms. Everything else — architecture, frameworks,
APIs — is how you arrange them.

### Phase C — Map research to building blocks

For each building block, consult the research to determine how it gets fulfilled:

1. **Use as-is** — the research identified an existing library, tool, or protocol
   that solves this building block directly. Use it. Don't rebuild what's solved.
2. **Adapt** — the research found a proven pattern or technique in another system
   that can be copied and adapted for this context.
3. **Build** — nothing in the research covers this. It must be built from scratch.
   Keep the interface small and the implementation replaceable.

For each choice, explicitly name the alternatives the research surfaced and why
they were selected or rejected. This is where decisions get logged.

If a building block has no research coverage, flag it. The user can either do
targeted research now or accept a lower-confidence decision.

### Phase D — Assemble the system

Now compose the building blocks into a system:

- **Boundaries** — where does one block end and another begin? What crosses a
  boundary (data, control, errors)?
- **Data flow** — how does data move through the system end-to-end?
- **Key interactions** — walk through the critical user workflows. What sequence
  of blocks does each touch?
- **Error propagation** — when a block fails, what happens? Who notices? How does
  the system recover?
- **Data model** — what are the core entities, relationships, and storage
  approach? What must be durable vs ephemeral?

### Phase E — Validate against constraints

Circle back to the constraints from Phase A:

- Does the assembled system satisfy every hard constraint?
- Where are the soft constraints compromised, and is that acceptable?
- What are the riskiest assumptions in the design?
- What would you prototype or spike first to reduce uncertainty?

### Rules

- **Start from constraints, not technology.** The product design tells you what
  must be true. Technology is how you make it true.
- **Ground decisions in research.** Every technology choice should trace back to
  something the research surfaced. If it doesn't, flag the gap.
- **Name the building blocks clearly.** If you can't explain what a piece does in
  one sentence, decompose further.
- **Challenge inherited patterns.** "That's how it's usually done" is not a
  rationale. Ask what problem the pattern solves and whether this system has that
  problem.
- **Log decisions as you go.** Don't batch them at the end.

## Step 4 — Log decisions

For EVERY significant technical decision surfaced during the session, save it
using the CLI. A "significant decision" is anything where alternatives were
considered or where the choice meaningfully affects the system.

For each decision, run:

```bash
mantle save-decision \
  --topic "<slugified-topic>" \
  --decision "<what was decided>" \
  --alternatives "<alt 1>" --alternatives "<alt 2>" \
  --rationale "<why this choice>" \
  --reversal-trigger "<what would change this>" \
  --confidence "<N/10>" \
  --reversible "<high|medium|low>" \
  --scope "system-design"
```

Log decisions as you go during the session, not all at the end.

## Step 5 — Save system design

After the session, compile the full design into a structured document and save:

```bash
mantle save-system-design --content "<full system design document>"
```

The document should be structured around the building blocks identified, not
around generic architecture headings. Sections should reflect the actual system
decomposition, not a template.

## Step 6 — Next steps

After a successful save, briefly assess this session before recommending next steps:

- Were any product design gaps discovered during system design?
- Did the design require decisions that the product design didn't anticipate?

**Valid next commands** (recommend the best fit, not all of them):

- `/mantle:plan-issues` — default. Recommend in most cases to break down the work into implementable issues.
- `/mantle:build` — recommend when the user wants to move fast and issues already exist. Automates shaping through verification in one pass.
- `/mantle:revise-product` — recommend when system design revealed gaps or contradictions in the product design that should be resolved before planning.

**Default:** `/mantle:plan-issues` if nothing suggests otherwise.

Present one clear recommendation with a reason, then mention alternatives briefly:

> **Recommended next step:** `/mantle:<command>` — [reason based on what you observed in this session]
>
> Other options: [brief list of alternatives with one-line descriptions]

## Session Logging

Before ending this session, write a session log:

    mantle save-session --content "<body>" --command "design-system"

Keep the log under ~200 words following the session log format (Summary, What Was Done, Decisions Made, What's Next, Open Questions).
