Design

---
name: design
description: >
  Produce architecture decisions — DB, auth, API, constraints.
  Use AFTER /requirements and BEFORE /breakdown. Step 2 of 7-step workflow. Maps to H8 (Find Your Voice).
user-invocable: true
argument-hint: "[--persist <slug>] [component or system to design]"
allowed-tools: ["Read", "Glob", "Grep", "Write", "AskUserQuestion"]
prev-skill: requirements
next-skill: breakdown
---

# Step 2: Design (วางโครงสร้าง)

**Habit**: H8 — Find Your Voice | **Anti-pattern**: Letting AI decide architecture without human judgment

## Process

1. **Read existing architecture and context contract**: Check `CLAUDE.md`, `AGENTS.md`, `SPEC.md`, `DOMAIN.md`, `CONTEXT.md`, `CONTEXT-MAP.md`, `DESIGN.md`, `ARCHITECTURE.md`, `docs/agents/domain.md`, and ADR directories. Understand current state and project vocabulary before proposing changes.

1b. **Validate scope alignment**: read the `SKILL_OUTPUT:requirements` block from `docs/specs/<slug>/prd.md` when persisted; otherwise recover `scope_in` / success criteria / `risks` from the PRD prose in context (non-persisted runs carry no block since v2.21.39, [#375](https://github.com/pitimon/8-habit-ai-dev/issues/375)). Then verify:

- Proposed architecture decisions don't expand beyond `scope_in`
- Success criteria are achievable with the proposed design
- Identified `risks` are addressed or accepted in design constraints

1c. **Select the smallest safe pass level** before producing design output:

| Pass level | Use when                                                                                                                                                      | Expected output                                                                                |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| **Scan**   | Small, bounded, exploratory, or unclear architecture impact                                                                                                   | Compact architecture note, key constraints, open questions, and safe next step                 |
| **Focus**  | One module, workflow, subsystem, integration, or boundary is in scope                                                                                         | Targeted decisions, local trade-offs, risks, and any needed ADRs                               |
| **Full**   | Whole-system design, unclear ownership, 3+ interacting modules, persistence, authentication, payment, security, deployment, or future-agent handoff is needed | Full decision set, ADR coverage, risk register, human approvals, and handoff-ready constraints |

Start with `Scan` unless the user's request or existing evidence proves a `Focus` or `Full` trigger. **Promote only with evidence, explicit user request, or risk of staying smaller** — then name the trigger, its evidence, and that risk.

2. **Identify decisions** that need human input:
   - Database choice and schema
   - Authentication/authorization approach
   - API contract (REST, GraphQL, MCP)
   - Service boundaries
   - Language and runtime (if greenfield or migration)
   - Framework selection (when alternatives exist)
   - Third-party dependencies

2b. **Label software ecology impact when AI/agent acceleration changes architecture concerns**:

- Use `software ecology impact` only when the acceleration affects a boundary, API contract, validation approach, release path, or ownership model.
- Treat it as an architecture concern, not a policy gate: capture the trade-off, owner, and validation implication inside the relevant decision or ADR.
- If the work merely changes copy, prompts, or local workflow with no architecture effect, skip the label.

3. **Present options** with trade-offs (not just one recommendation):

   ```
   ## Decision: [Topic]
   **Option A**: [Description] — Pro: [x], Con: [y]
   **Option B**: [Description] — Pro: [x], Con: [y]
   **Recommendation**: [Which and why]
   ```

   Before giving the recommendation, **steelman the option(s) you are about to reject** — state the strongest case for each, then justify the choice. Rejecting a strawman lets it resurface next cycle (commandment 14, `integrity-principles.md`).

4. **Human must decide**: AI proposes, human disposes. Mark each decision as In-the-Loop.

4a. **Label architecture claims before relying on them**. Do not present uncertain structure as confirmed architecture.

| Claim label           | Meaning                                                                                     |
| --------------------- | ------------------------------------------------------------------------------------------- |
| **Confirmed**         | Directly supported by files, existing docs, command output, or explicit user-provided facts |
| **Inferred**          | Reasoned from evidence, but not directly stated or exhaustively verified                    |
| **Proposed**          | Suggested future architecture or change, not implemented or approved yet                    |
| **Assumed**           | Working premise used to move forward; replace with evidence when load-bearing               |
| **Unknown**           | Important gap that is not yet known                                                         |
| **Requires approval** | Decision or claim that needs explicit human acceptance before it becomes a constraint       |

For load-bearing claims, include evidence strength and verification need:

| Evidence strength | Use when                                                                      |
| ----------------- | ----------------------------------------------------------------------------- |
| **Direct**        | The cited file, doc, command, or user statement directly supports the claim   |
| **Inferred**      | Multiple signals support the claim, but no single source directly confirms it |
| **Assumed**       | The claim is an explicit temporary premise                                    |
| **Unverified**    | The claim has no reliable source yet and must not drive irreversible design   |

Use `Verify first: Yes` for any claim that affects sticky decisions, security, compliance, data model, auth boundary, public API, deployment, or irreversible user impact. Use `Verify first: No` only when the claim is already direct evidence or low-impact.

4b. **Prioritize architecture-impacting questions**:

| Priority      | Meaning                                                                               |
| ------------- | ------------------------------------------------------------------------------------- |
| **Blocking**  | A wrong answer can change the architecture, invalidate an ADR, or create major rework |
| **Important** | The answer changes trade-offs, sequencing, risk, or verification plan                 |
| **Useful**    | The answer improves clarity but can be safely assumed or deferred                     |

Ask `Blocking` questions before final recommendations. For `Important` or `Useful` questions, either ask or proceed with a clearly labeled assumption.

5. **Identify sticky decisions** (decisions that should not change mid-implementation):

   Some decisions act as **sticky latches** — once set, reversing them mid-session wastes prior context (like a flag that, once flipped, invalidates the prompt cache).

   For each decision in step 4, ask: **"If we change this after implementation starts, how much rework does it cause?"**

   | Rework Level | Classification                                                | Example                          |
   | ------------ | ------------------------------------------------------------- | -------------------------------- |
   | >50% redo    | **Sticky** — commit now, revisit only via new `/design` cycle | DB choice, auth model, API style |
   | 10-50% redo  | **Semi-sticky** — can adjust but flag the cost                | ORM choice, test framework       |
   | <10% redo    | **Flexible** — change freely during implementation            | Variable names, UI copy          |

   Mark sticky decisions explicitly in the ADR or design doc:

   > **STICKY**: This decision is load-bearing. Changing it requires re-running `/design`, not patching mid-build.

   This is H2 in practice: define done before starting, including which decisions ARE the definition of done.

5b. **Decision granularity heuristic** (H3):

- If one decision affects >3 layers (data + API + auth + UI), split into sub-decisions
- If multiple decisions share the same trade-offs, group them into one ADR
- Each ADR should have exactly one "Decision maker" — avoid committee deadlock

6. **Article 14 Human-Oversight Checkpoint** (for AI-system designs):

   If the system being designed is an **AI system that may target the EU market** (or any high-risk AI system regardless of market), confirm the design satisfies EU AI Act Article 14 capabilities. Answer for each:

   | Capability (Art. 14)  | Question                                                                            | Pass? |
   | --------------------- | ----------------------------------------------------------------------------------- | ----- |
   | ¶4(a) Understand      | Can humans understand the system's capacities and limitations and detect anomalies? | Y/N   |
   | ¶4(b) Automation bias | Are humans aware of and protected from over-reliance on AI output?                  | Y/N   |
   | ¶4(c) Interpret       | Can humans correctly interpret the system's output?                                 | Y/N   |
   | ¶4(d) Override        | Can humans disregard, override, or reverse the output?                              | Y/N   |
   | ¶4(e) Stop button     | Can humans intervene OR trigger a 'stop' procedure for safe halt?                   | Y/N   |

   **All five must be YES for high-risk AI deployment to the EU.** If any are NO, the design needs revision before proceeding to `/breakdown`.

   > 🔗 **Skip if**: System is not AI-based, or is AI but not high-risk under Annex III, or not EU-targeted. For formal scope pre-flight, install [`pitimon/claude-governance`](https://github.com/pitimon/claude-governance) v3.1.0+ and run `/eu-ai-act-check --scope` (the canonical skill, migrated from this plugin on 2026-05-02 per ADR-012).
   >
   > 🔗 **Three Loops** (formal per-decision classification) lives in `claude-governance` (ADR-002); cite Article 14 ¶ refs in audits, not Three Loops labels.

7. **Document as ADR** if the decision is:
   - Hard to reverse
   - Affects >3 files
   - Changes public API

7b. **Use diagrams only when they clarify architecture**:

- Use Mermaid only when it clarifies boundary, data flow, workflow, module relationship, or ownership.
- Every node must trace to evidence, assumption, or proposal. Label uncertain nodes rather than drawing them as fact.
- Split large diagrams by architecture question instead of creating one unreadable all-in-one diagram.
- Do not create decorative diagrams that do not help a future human or agent make a decision.

8. **H8 Checkpoint**: "Do I understand WHY we're building it this way, not just WHAT?"
   Also check all 4 dimensions: Body (CI/infra ready?), Mind (serves roadmap?), Heart (good DX/UX?), Spirit (security/ethics defaults baked in?).

## Handoff

- **Expects from predecessor** (`/requirements`): PRD summary with scope and success criteria
- **Produces for successor** (`/breakdown`): Architecture decisions (ADRs), technology choices, constraints

## Optional Persistence (`--persist <slug>`)

When invoked with `--persist <slug>`, this skill writes its design output to `docs/specs/<slug>/design.md`, and the `SKILL_OUTPUT:design` block lives in that file (not the conversation). Without the flag: no file writes and no block ([#375](https://github.com/pitimon/8-habit-ai-dev/issues/375)).

Persistence rules: an invalid slug (`^[a-z0-9][a-z0-9-]{1,63}$`) skips persistence only. If the file exists, ask overwrite / `design.vN.md` / abort (no way to ask: `.vN.md` + one warning). Frontmatter: `feature`, `step`, `created`, `updated`, `source-skill-version`. Errors state attempt, cause, next step; if the directory cannot be created, show the result in the reply without a block. Completion line: `[/design] complete → docs/specs/<slug>/design.md`. Details: `${CLAUDE_PLUGIN_ROOT}/guides/persistence-convention.md`.

ID-linkage tip: when persisting, label each decision as `### Decision-N: <topic>` and cite covered requirements as `Decision-N covers: FR-001, FR-003` to enable deterministic Coverage and Inconsistency passes in `/consistency-check`. IDs are recommended, not required.

## When to Skip

- Solo bug fix that follows an existing, established pattern
- Cosmetic or UI-only change with no architecture impact
- Change already covered by a previously accepted ADR

## Definition of Done

- [ ] At least 2 options presented with trade-offs for each key decision
- [ ] Human has explicitly decided (not AI default) — decision recorded
- [ ] ADR created for decisions affecting >3 files or changing public API
- [ ] Constraints and non-goals documented
- [ ] Existing glossary/context files and ADRs were checked when present; glossary conflicts surfaced; an ADR stands unless the user asks to revisit it
- [ ] AI/agent acceleration work labels `software ecology impact` when it affects boundaries, API contracts, validation, release, or ownership
- [ ] Pass level, claim labels, evidence strength, and `Verify first: Yes/No` are recorded for load-bearing claims

## Structured Output

**Emit this block only into the persisted `docs/specs/<slug>/design.md` when `--persist` is used** — never to the conversation response (the HTML comment is visible noise in Codex; see [`guides/structured-output-protocol.md`](https://github.com/pitimon/8-habit-ai-dev/blob/main/guides/structured-output-protocol.md) §"Emission gate"). The fenced block below is the **file template**:

Regardless of persistence, end your conversation output with the plain-text line `[/design] complete` — see [`guides/structured-output-protocol.md`](https://github.com/pitimon/8-habit-ai-dev/blob/main/guides/structured-output-protocol.md) §"Completion signal".

```
[/design] COMPLETE SKILL_OUTPUT:design
<!-- SKILL_OUTPUT:design
pass_level: [Scan|Focus|Full]
decision_count: [N]
decisions:
  - "[decision 1: e.g., PostgreSQL for persistence]"
  - "[decision 2: e.g., REST API with versioned endpoints]"
sticky_decisions:
  - "[sticky 1: e.g., PostgreSQL — >50% rework to change]"
constraints:
  - "[constraint 1]"
load_bearing_claims:
  - "[Confirmed|Inferred|Proposed|Assumed|Unknown|Requires approval: claim; Evidence: Direct|Inferred|Assumed|Unverified; Verify first: Yes|No]"
approval_required:
  - "[Blocking|Important|Useful: decision or question]"
adr_references:
  - "[ADR-NNN: title]"
article_14_applicable: [true|false]
article_14_pass: [true|false|n/a]
END_SKILL_OUTPUT -->
```

Place this at the very end of the persisted `design.md` file, after all human-readable content.

## Further Reading

See [Step 2 wiki page](https://github.com/pitimon/8-habit-ai-dev/blob/main/docs/wiki/Step-2-Design.md) for deeper walkthrough, examples, and common pitfalls.

Load `${CLAUDE_PLUGIN_ROOT}/guides/templates/adr-template.md` for the output template.
Load `${CLAUDE_PLUGIN_ROOT}/guides/behavioral-spec-craft.md` for spec-writing craft — precedence/override ordering, invariants over mechanics, trust-boundary declaration (techniques 2, 5, 7).
Load `${CLAUDE_PLUGIN_ROOT}/habits/h8-find-voice.md` for the full H8 principle and examples.
Load `${CLAUDE_PLUGIN_ROOT}/guides/persistence-convention.md` when `--persist <slug>` is used (canonical spec for opt-in persistence to `docs/specs/<slug>/design.md`).
Load `${CLAUDE_PLUGIN_ROOT}/guides/project-context-contract.md` when repo-local glossary, issue-tracker, or agent context files are present.

---

Hermes: no `${CLAUDE_PLUGIN_ROOT}`; use `https://github.com/pitimon/8-habit-ai-dev/blob/main` ([#388](https://github.com/pitimon/8-habit-ai-dev/issues/388)). OpenClaw: use the bundled file or `{baseDir}`; otherwise use the same GitHub URL.