# Write Design

> Produces a diagram-centric high-level design under `./design/`, built on Mermaid component, flow, sequence, data-model, class, or state diagrams plus architecture rationale. Use for HLDs, architecture and system diagrams, flowcharts, or design visualization.

- Skill: `abchoudh-amd/write-design` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add abchoudh-amd/write-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/abchoudh-amd/write-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: abchoudh-amd (https://skillmd.com/u/abchoudh-amd)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/abchoudh-amd/write-design

---


# Write Design

Produce a diagram-centric high-level design document that makes an architecture
legible before problem framing, planning, or implementation exists. Diagrams use Mermaid (the repo
standard); prose explains rationale, component responsibilities, and alternatives.

## Quick start

1. Inspect the repository, then confirm the design scope and requested depth.
2. Route the current inventory through
   [question routing](../_shared/QUESTION-ROUTING.md), which selects
   between one `grill-me` pass and a controlled HLD questionnaire pause.
3. Recalculate after every response until the current inventory is empty;
   there is no fixed pass limit.
4. Pick the diagram set using the selection guide below.
5. Draft the HLD in memory from `templates/hld.md`, filling each section and
   embedding diagrams.
6. Run the complete pre-save self-check, route any newly exposed questions
   again, record whatever remains deferred under `## Open questions`, and save
   under `./design/`.

## Codebase-first rule

If a question can be answered by exploring the repo, explore first instead of asking.

1. Check relevant code, modules, schemas, config, and existing diagrams.
2. State findings with `file:line` evidence.
3. Ask only the remaining uncertainty.

Prefer "I checked X and recommend Y" over asking for facts already in the codebase.

Inventory material architecture decisions across boundaries, components,
dependencies, interfaces, flows, data/state lifecycle, failure recovery,
security, performance, operability, alternatives, and compatibility. Count
only currently answerable decisions after repository facts are removed;
dependent answers may expose another iteration.

Route that inventory through
[question routing](../_shared/QUESTION-ROUTING.md). Its one-to-three route
asks the complete inventory in one [`grill-me`](../grill-me/SKILL.md) pass and
then recalculates. Its four-or-more route dispatches
`rocprof-compute-decision-questionnaire-writer` in `hld-initial` or, for a later
newly exposed inventory, `hld-follow-up`; report the exact saved path and pause.
Resume only from that completed exact path and validate its ordered lineage
under the shared orchestration contract. An incomplete or malformed
questionnaire receives a correction request for the same path and continues to
block the HLD; it does not authorize a draft or repair version.

## Authoring rules

The template mirrors the rocprofiler-compute HLD template in `docs/design/`, so a
saved HLD body drops into that directory unchanged. Its authoring rules apply here:

- Articulate **why** — why this is a problem, why a decision was made — not just what.
- Be short and specific. No word-fluff that inflates length, no invented terminology
  where simple wording works.
- **Table and diagram before paragraph.** Anything enumerable is a table: comparing two
  approaches, mapping a condition to its required behavior, listing which options
  interoperate, requirements, validation checks. Anything structural or sequential is a
  diagram. Prose earns its place by carrying a **why** that neither can. This does not
  thin System Context or Problem statement — they stay the heaviest sections, and a
  table-dense one still argues.
- **Requirements carry stable IDs.** `FR-n` for functional, `NFR-n` for non-functional,
  grouped by topic once the list outgrows a single table. Implementation phases and
  validation checks cite those IDs instead of restating the requirement.
- Keep decisions localized and structured. Do not spread one decision across the
  document. Each `###` subsection under Design settles one decision and is named after
  it.
- Strengthen arguments with concrete data: estimations, measurements, worked examples.
- Avoid detail that goes stale fast. Code locations, variable names, and class names
  do not belong in the HLD body. This does not weaken the codebase-first rule:
  `file:line` evidence is for the conversation while resolving decisions, not for the
  saved document.
- Use bullets, tables, and indentation to accent points, not as visual noise.
- **System Context and Problem statement carry the most weight.** Design quality tracks
  how well the current system and the problem are articulated; write them first.

Upstream cautions against producing an HLD with AI tools. The substance behind that
caution is preserved by the decision router: resolve material architecture decisions
with the user or with repository evidence, and never invent an answer to fill a section.

## Diagram selection guide

Pick the minimal set that explains the design. Most HLDs need a component graph plus
one or two flow diagrams. A diagram goes wherever it carries the explanation, not in one
reserved section: the mechanics of the current system or an external contract the design
depends on belong in System Context, a cost or alternative comparison in Problem
statement, proposed structure and decision logic in Design.

| Intent | Diagram | Mermaid type | Usually goes in |
|---|---|---|---|
| System structure, components, boundaries, dependencies | Component / architecture | `graph TD` / `graph LR` | `## Design`, or `## System Context` for today's structure |
| Process, branching logic, decision points | Flowchart | `flowchart TD` | `## Design`, or `## Problem statement` to contrast two approaches |
| Interaction between actors/services over time | Sequence | `sequenceDiagram` | `## Design`, or `## System Context` for an external mechanism |
| Entities and relationships | Data model | `erDiagram` | The `## Design` subsection that owns the persisted state |
| Types, methods, structural relationships | Class | `classDiagram` | The `## Design` subsection that owns the structure |
| Lifecycle, modes, state transitions | State | `stateDiagram-v2` | The `## Design` subsection that owns the lifecycle |

See [REFERENCE.md](REFERENCE.md) for a minimal valid block per type.

## HLD document template

Copy `templates/hld.md` and fill it. The seven `##` sections, their names, order,
and casing match the rocprofiler-compute template exactly; do not add, rename, or
reorder them. That contract covers `##` only — every `###` subsection is yours to
name and order.

1. **System Context** — what the in-scope part of the system does today, what it does
   not cover, its main and surrounding components, plus assumptions and constraints.
2. **Problem statement** — what problems this design solves, why they matter, impact.
3. **Requirements** — `### Functional requirements` and `### Non-functional requirements`
   as ID-keyed tables, plus explicit non-goals.
4. **Design** — free-form, as upstream leaves it. Name each subsection after the decision
   it settles. Two obligations: at least one diagram of the proposed structure or its
   decision logic, and every architectural decision stated with its rejected alternative
   and why, inside the subsection that owns it. Data-model or state content appears only
   when something is persisted or stateful; there is no placeholder heading when nothing is.
5. **Implementation phases** — vertical slices, each delivering incremental user value,
   citing the requirement IDs it satisfies.
6. **Validation, security and debuggability** — `### Validation` as numbered checks with
   their pass criteria and the test types realizing them, then `### Security` and
   `### Debuggability`. Retained risks and their mitigations go here.
7. **Open questions** — known unknowns, deferred decisions, trade-offs, or `none`.

See [REFERENCE.md](REFERENCE.md) for expand/collapse rules and [EXAMPLES.md](EXAMPLES.md)
for worked HLDs.

## Hand-off rule

The HLD may precede and complement a formulation and feature plan. For planning-only
feature work, recommend that the user start `plan-feature` with it; for full delivery,
recommend `build-feature`. Never invoke either — they are human front doors.
Those coordinators own questionnaire creation, exact-path human pauses, formulation,
planner questions, approval, and publication. Architecture and diagrams are settled here;
link the decision-questionnaire lineage and related artifacts without duplicating them.
Executable task sequencing belongs to the
selected feature coordinator or the integrated `refactor` workflow.

## Routing

- Diagram-centric HLD, architecture rationale, or system/flow visualization →
  stay in `write-design`.
- Unit-level design below the architecture — exact signatures, error contracts, or a
  per-unit test plan → [`write-lld`](../write-lld/SKILL.md), which links this HLD and
  inherits its `FR-n` / `NFR-n` IDs.
- Raw problem framing, HLD-backed feature intake, executable planning, or task
  sequencing → `plan-feature` for planning only, `build-feature` for full delivery, and
  `implement-feature` for one exact approved feature plan. Do not dispatch
  feature-planning components from `write-design`. A direct one-off questionnaire or
  formulation request may still use the standalone controlled component flow.
- Behavior-preserving planning and refactor phases → [`refactor`](../refactor/SKILL.md).
- An architecture decision already made and needing contest rather than a diagram has
  no Cursor route. Contesting a decision requires blind read-only attackers, and Cursor
  has no enforced read-only agent profile to dispatch them under. Raise it with the
  human instead of reasoning about it inline, since a coordinator cannot blind itself
  to its own rationale.
- Implementation code. Stop after the HLD. A bare implementation request without an
  approved plan or released `plan_ready` state stops and offers `plan-feature` or
  `build-feature`. For an explicitly authorized single-edit atomic non-Jira request, the
  main coordinator may discover exact paths read-only, create a boundary manifest, and
  dispatch `rocprof-compute-blind-source-writer` in `atomic` mode.
- Sphinx RST documentation pages. The main coordinator first resolves exact targets and
  `edit`/`create` mode, then dispatches `rocprof-compute-docs-writer` with a one-time
  boundary manifest.

## Pre-save self-check and question loop

1. Every embedded Mermaid block parses (see REFERENCE validation note).
2. Each diagram is referenced by the surrounding prose, not dropped in unexplained.
3. System Context, Problem statement, Requirements, Design, and Validation,
   security and debuggability are present and non-empty.
4. The seven `##` headings match the template's names, order, and casing. `###`
   subsections are unconstrained.
5. Every architectural decision under Design names its rejected alternative and why.
6. Requirements carry `FR-n` / `NFR-n` IDs, and the phases and validation checks cite
   them rather than restating the requirement.
7. Rebuild the current material-question inventory from the in-memory draft,
   route it through [question routing](../_shared/QUESTION-ROUTING.md),
   then rerun the complete self-check. Repeat after every revision; there is no
   fixed pass limit.

Run the router to exhaustion before saving. A decision that survives it — because it
depends on information nobody has yet, or was consciously deferred — goes under
`## Open questions` with why it is deferred and what would resolve it. An unanswerable
question no longer blocks the save, but an unrouted one does: never move a question
there to skip a `grill-me` pass or a questionnaire. Retained risks with mitigations are
not open questions; they belong under Validation, security and debuggability.

On questionnaire resume, accept only the completed exact saved path named by the pause.
If validation fails, request a precise correction to that same path, remain paused, and
create neither the HLD nor a replacement questionnaire merely to repair it.

## File output rules

1. Ensure `./design/` exists at the repo root; create it if missing.
2. Save as `./design/<feature-name>.md` using kebab-case.
3. If the target filename already exists, auto-suffix `-v2`, `-v3`, ... rather than overwriting.
4. Echo the saved path in the final response.

## Additional resources

- [REFERENCE.md](REFERENCE.md) — Mermaid cheat-sheet per diagram type, validation, collapse rules.
- [EXAMPLES.md](EXAMPLES.md) — worked HLDs.
- [templates/hld.md](templates/hld.md) — the HLD skeleton.
- [decision-questionnaire orchestration](../_shared/DECISION-QUESTIONNAIRE-ORCHESTRATION.md)
  — hybrid routing, controlled questionnaire lineage, and exact-path resume.
- [writing style](../_shared/WRITING-STYLE.md) — normative prose rules and the pre-save self-check for
  every human-read artifact this skill produces.
- [design principles](../_shared/DESIGN-PRINCIPLES.md) — the structure an HLD proposes.
  Read as an author: components, their dependencies, and the interfaces between them
  satisfy these before the diagram is drawn.