# Write Lld > Produces a low-level design under `./design/-lld.md` stating the modules, exact signatures, error behavior, and test plan an approved architecture needs before implementation, with Mermaid class, sequence, state, and flow diagrams. Use for LLDs, detailed design, interface or API contracts, class and method design, or a unit-level test plan. - Skill: `abchoudh-amd/write-lld` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add abchoudh-amd/write-lld` - Raw SKILL.md: https://api.skillmd.com/api/skills/abchoudh-amd/write-lld/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: abchoudh-amd (https://skillmd.com/u/abchoudh-amd) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/abchoudh-amd/write-lld --- # Write LLD Produce a low-level design that an implementer can build from without redeciding anything. An HLD settles which components exist; this document settles what each unit is called, what it takes, what it returns, how it fails, and which test proves it. Diagrams use Mermaid (the repo standard); prose carries the reasoning a table cannot. ## Quick start 1. Inspect the repository and read the HLD if one exists. Confirm the change in scope and the files it touches. 2. Inventory the material unit-level decisions left after repository facts are removed. 3. Resolve them with one [`grill-me`](../grill-me/SKILL.md) pass, then recount. Repeat until the inventory is empty; there is no fixed pass limit. 4. Pick the diagram set using the selection guide in [`LLD-CONTRACT.md`](../_shared/LLD-CONTRACT.md). 5. Draft the LLD in memory from `templates/lld.md`, filling each section. 6. Run the pre-save self-check, grill on anything the draft newly exposed, record what stays 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. This binds harder here than in an HLD: an LLD that names a function nobody read is a guess. 1. Read the modules, call sites, tests, fixtures, and config the change touches. Cursor has no delegated read-only survey role, so the coordinator explores inline. 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 unit-level decisions across responsibility placement, interface shape, types, error contracts, state and lifecycle, concurrency, data and schema shape, backward compatibility, and test strategy. Count only currently answerable decisions; dependent answers may expose another iteration. ## HLD intake An HLD is the preferred input and not a precondition. | Situation | What to do | | --- | --- | | An HLD exists | Read it, name it in the Scope and inputs table, and inherit its `FR-n` / `NFR-n` IDs. Cite them; never restate or renumber them. | | No HLD exists and the change is unit-level | Proceed. Declare the `FR-n` / `NFR-n` this design satisfies under `## Scope and inputs`. | | No HLD exists and the request is really about component boundaries | Say so and recommend [`write-design`](../write-design/SKILL.md) first. Do not settle an architecture decision inside an LLD. | | The HLD and the code disagree | Record the conflict in the draft, raise it, and do not silently redesign. An architecture change belongs in a revised HLD. | Never revise an HLD from here. An LLD that contradicts its own linked HLD is a finding, not a design. ## Document contract The authoring rules, the diagram selection guide, the seven `##` sections, and the pre-save self-check live in [`LLD-CONTRACT.md`](../_shared/LLD-CONTRACT.md). Read it before drafting and follow it exactly. The controlled `rocprof-compute-lld-writer` role obeys the same file, so an LLD written here and one written inside a feature workflow are the same document. Copy `templates/lld.md` and fill it. See [REFERENCE.md](REFERENCE.md) for the altitude table, a minimal valid Mermaid block per type, and expand/collapse rules, and [EXAMPLES.md](EXAMPLES.md) for worked LLDs. ## Question loop Unresolved decisions go to [`grill-me`](../grill-me/SKILL.md) and nowhere else. There is no controlled LLD questionnaire and no `lld` domain in the count-based router of [`QUESTION-ROUTING.md`](../_shared/QUESTION-ROUTING.md): unit-level choices are answerable in a live turn, and no later agent consumes an LLD questionnaire as immutable lineage. Ask the complete current inventory, incorporate the answers, repeat discovery, and recount. Run that loop to exhaustion before saving. A decision that survives it — deferred by the user, or dependent on information nobody has yet — goes under `## Open questions` with why it is deferred and what would resolve it. An unanswerable question no longer blocks the save; an unasked one does. ## Pre-save self-check Run the numbered self-check in [`LLD-CONTRACT.md`](../_shared/LLD-CONTRACT.md) before every save. Its last step — rebuild the decision inventory from the in-memory draft, resolve it, rerun the whole check — resolves through [`grill-me`](../grill-me/SKILL.md) here, since this skill has no questionnaire alternative. ## Hand-off rule An LLD is an input to planning, never a plan. It carries no branch, no base, no work package, and no approval receipt. For planning-only feature work, recommend that the human start `plan-feature` with the saved path; for full delivery, recommend `build-feature`. Never invoke either — they are human front doors. Inside one of those workflows the LLD is not written by this skill at all: the coordinator dispatches the controlled `rocprof-compute-lld-writer` between the published formulation and the feature planner, under this same document contract, and the human approves its exact bytes. A coordinator or a spawned agent never invokes this skill to get there. Use this skill directly when the human wants an LLD on its own — before a feature workflow exists, alongside a refactor, or to settle an interface with no ticket behind it. ## File output rules 1. Ensure `./design/` exists at the repo root; create it if missing. 2. Save as `./design/-lld.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. ## Routing - Architecture, component boundaries, or a system diagram → [`write-design`](../write-design/SKILL.md). - A map of the code as it is today, extracted mechanically → [`understand-codebase`](../understand-codebase/SKILL.md). Its `./codemap/` output is an input here, not a substitute for Current implementation. - Executable planning and task sequencing → `plan-feature`; combined planning and delivery → `build-feature`; one exact approved feature plan → `implement-feature`. See the hand-off rule above: both feature coordinators own their own LLD stage. - Behavior-preserving restructuring → [`refactor`](../refactor/SKILL.md), which owns its own phase plan. - A design decision already made and needing contest rather than documentation 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. ## Out of scope - Implementation code. Stop after the LLD. Route full behavior-changing delivery to `build-feature`; route one exact approved plan to `implement-feature`. 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. - Writing the tests the test plan describes. The plan names checks and target files; the main coordinator dispatches `rocprof-compute-unit-test-writer` or `rocprof-compute-cli-test-writer` with its own manifest. - Executable feature planning, work packages, branches, and approval receipts. Route to `plan-feature`. Never invoke a feature skill from here — all three are human front doors. - Architecture decisions. Route to `write-design`. - 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. ## Additional resources - [REFERENCE.md](REFERENCE.md) — the HLD/LLD altitude table, traceability contract, Mermaid cheat-sheet, interface conventions, collapse rules, and document shapes. - [EXAMPLES.md](EXAMPLES.md) — worked LLDs. - [templates/lld.md](templates/lld.md) — the LLD skeleton. - [LLD contract](../_shared/LLD-CONTRACT.md) — the authoring rules, diagram selection guide, seven-section contract, and pre-save self-check this skill and the controlled `rocprof-compute-lld-writer` both follow. - [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 LLD specifies. Read as an author: responsibility placement, dependency direction, and what each unit exposes satisfy these before a signature is written down.