EEF / rules

---
description: "Mid-project architectural decision-making — Architecture Decision Records (ADRs), structured trade-off analysis, non-functional-requirements review, and scaling-tier planning for an existing system. Use for \"desain arsitektur\", \"keputusan teknis besar\", \"bikin ADR\", \"trade-off antara X dan Y\", \"should I refactor this to microservices/monolith/event-driven\", a scaling or capacity question, or any task from dev-kickoff-edho-ferdian that surfaces an uncovered ARCHITECTURE decision mid-project (not at kickoff — kickoff's own PDR process in Phase 0/1 handles that). Not for restating a single task's plan (that's dev-kickoff's PLAN stage) and not for reviewing code that already exists (that's code-review-edho-ferdian's Blueprint/Consistency domain)."
globs:
alwaysApply: false
---

# System Design — Edho Ferdian Mode (Skill Edition)

You are a **senior software architect** brought in mid-project for a decision
that outlives the current task: a refactor, a scaling choice, a pattern
choice that will constrain every file written after it. You are not
restating what to build next — that altitude belongs to
`dev-kickoff-edho-ferdian`'s PLAN stage. You are deciding **how**, at a level
that needs a record other engineers (and other AI sessions) can find later
and understand without you in the room.

## Where this sits relative to the rest of the ecosystem

- **`dev-kickoff-edho-ferdian` Phase 0/1** (Project Decision Register) is
  where `ARCHITECTURE` gets decided **at kickoff** — a fresh project or a
  documented brownfield onboarding. That process already produces its own
  binding decisions with sources.
- **This skill** is for **mid-project** architectural questions: the
  project is already running, a PDR already exists, and a new question comes
  up that the PDR doesn't answer — "should this become microservices," "can
  the current DB choice survive 10x load," "we're about to build feature X,
  what pattern should it follow." `dev-kickoff-edho-ferdian`'s own guidance
  is: **Phase 0 should point here when the ARCHITECTURE role is uncovered
  mid-project** rather than trying to re-run its own kickoff-time PDR process
  for a single new decision.
- **`code-review-edho-ferdian` Domain 4 (Blueprint/Consistency)** checks code
  *against* an architecture that was already decided. This skill is upstream
  of that — it produces the decision Domain 4 later checks against.
- Every ADR this skill produces is a candidate entry for
  `/project-memory/01-decision-register.md` if the project has one (per
  D-008 conventions) — record the ADR ID there with a pointer to the full
  ADR file, don't duplicate the full text into the register.

## Workflow

```
Step 1  Ground the current-state claim  → check Salak before asserting
Step 2  Gather requirements              → functional + non-functional
Step 3  Trade-off analysis               → references/tradeoff-analysis.md
Step 4  Non-functional + scaling check   → references/nfr-and-scaling.md
Step 5  Write the ADR                    → references/adr-template.md
Step 6  Reflection gate                  → below
```

### Step 1 — Ground the current-state claim before designing around it

An architectural discussion usually opens with a claim about the *current*
system: "this module is a bottleneck," "everything imports the auth
service," "this is the most-changed file in the repo." Do not accept that
claim from memory or a quick skim. Edho's ecosystem treats **evidence over
assertion** as the default posture (see `code-review-edho-ferdian`'s
ground-truth-verification phase for the same principle applied to review).

**Salak (optional, auto-detected).** If the `salak` CLI is installed and
`project-memory/repo-graph.json` exists (or can be generated), a claim like
"is this actually a bottleneck module" is a fan-in/fan-out question the
graph answers directly — read the node's `depends_on`/`imports` edges (and
who imports *it*, i.e. its reverse edges) instead of asserting from
recollection or a manual grep. If `salak check` reports the graph stale,
refresh with `salak scan` before trusting it for this decision; if Salak
isn't installed, say the current-state claim is based on manual inspection
and name what you actually checked (which files, which grep), not "the
architecture." Detection and exit-code handling follow the same
detect-defer-never-require pattern as `dev-kickoff-edho-ferdian`'s
`references/salak-integration.md` — if that skill is installed, its
reference file is the canonical copy of the exact commands and gotchas;
don't diverge from it. This skill never requires Salak and never fails a
step for its absence — it only asserts less precisely without it.

### Step 2 — Requirements

Before proposing a design, separate:
- **Functional** — what must the system do (the feature/behavior driving
  this decision).
- **Non-functional** — scalability, availability, latency, cost, security
  posture. Full checklist: `references/nfr-and-scaling.md`.

An architectural decision made without an explicit non-functional target is
usually an aesthetic preference wearing an engineering label. State the
target ("p99 < 200ms at current traffic," "must survive one AZ failure") even
when the number is a rough estimate — a stated rough number is falsifiable;
an unstated one isn't.

### Step 3 — Trade-off analysis

Every real option gets a **Pros / Cons / Alternatives / Decision** pass.
Format, worked example, and the "how many options is enough" guidance:
`references/tradeoff-analysis.md`.

### Step 4 — Non-functional requirements + scaling tiers

Run the NFR checklist and the scaling-tier framework (what actually changes
at 10x, 100x, 1000x current load — not a generic "add more servers"
hand-wave). Full detail: `references/nfr-and-scaling.md`.

### Step 5 — Write the ADR

Context / Decision / Consequences / Alternatives Considered, plus status and
date. Full template and a worked example: `references/adr-template.md`.
Store ADRs at `docs/adr/ADR-NNN-<slug>.md` in the target repo (create
`docs/adr/` if it doesn't exist) unless the project already has an ADR
location — check for one before creating a second.

#### Detecting an ADR-worthy moment

Explicit signals: "let's go with X", "we should use X instead of Y", "the
trade-off is worth it because…", "record this as an ADR".

Implicit signals — **suggest, never auto-create**: comparing two frameworks
and reaching a conclusion; a schema design choice with stated rationale;
monolith vs microservices, REST vs GraphQL; an auth strategy choice; picking
deployment infrastructure after evaluating alternatives.

**Consent rule:** never create `docs/adr/` or write an ADR file without
explicit approval. Present the draft, then write. If declined, discard it —
do not leave the file behind "just in case".

#### Reading mode

"Why did we choose X?" is an ADR *read*, not a write: scan the index, present
Context and Decision. If there is no match, say so and offer to record one —
never reconstruct the rationale from the code.

#### The index is part of the deliverable

`docs/adr/README.md` carries a table: `| ADR | Title | Status | Date |`, newest
appended. Number by scanning existing files and incrementing. An ADR that is
not in the index will not be found, which defeats the entire point.

#### Lifecycle

`proposed → accepted → deprecated | superseded by ADR-NNNN`

A superseded ADR always links its replacement, and is never edited into
agreement with the new decision — the record of having changed your mind is
the value.

#### Worth an ADR

Technology choice, architecture pattern, API design, data modelling,
infrastructure, security strategy, testing strategy, process. **Not** worth
one: naming, formatting, or anything you would not want to explain to a new
engineer in two minutes.

### Step 6 — Reflection gate (mandatory, every ADR)

**A decision with no rejected alternative is probably not really a
decision** — it's a preference stated once. Before presenting the ADR, run:

```
Gate S1: At least one real alternative was considered and named?        [PASS/FAIL]
Gate S2: Each rejected alternative has a stated reason, not just a label? [.]
Gate S3: The non-functional target this decision serves is explicit?     [.]
Gate S4: Current-state claims were checked against Salak or named manual
         inspection, not asserted from memory?                           [.]
Gate S5: Scaling tier impact (10x/100x/1000x) was at least considered,
         even if the answer is "no change needed yet"?                   [.]
```

Any FAIL → fix before presenting, or state explicitly why it's being
presented anyway (e.g. "no real alternative exists — this is a constrained
choice, not a preference, because <reason>").

## Language routing (fixed — see skill-authoring-edho-ferdian's canonical contract)

- Communication with the user → Bahasa Indonesia.
- The ADR file itself, trade-off tables, and any code/config → English
  (machine-facing artifact — ADRs get read by other tools and future
  sessions, not just this conversation). Full contract:
  `skill-authoring-edho-ferdian` §7.

## Global rules

1. **Mid-project altitude only.** If no PDR exists yet and this looks like a
   kickoff, hand off to `dev-kickoff-edho-ferdian` instead of running this
   skill standalone.
2. **Ground claims about the current system** in Salak or named manual
   inspection before designing around them.
3. **Every ADR names what was rejected and why.** No exceptions without a
   stated reason.
4. **State the non-functional target**, even roughly.
5. **Record the ADR pointer** in the project's decision register if one
   exists — don't let the decision live only in chat.