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, 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. Its one-to-three route asks the complete inventory in one grill-me 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.

See 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 for expand/collapse rules and 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, 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.
• 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, 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 — Mermaid cheat-sheet per diagram type, validation, collapse rules.
• EXAMPLES.md — worked HLDs.
• templates/hld.md — the HLD skeleton.
• decision-questionnaire orchestration — hybrid routing, controlled questionnaire lineage, and exact-path resume.
• writing style — normative prose rules and the pre-save self-check for every human-read artifact this skill produces.
• design principles — the structure an HLD proposes. Read as an author: components, their dependencies, and the interfaces between them satisfy these before the diagram is drawn.