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 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.
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.

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. 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 for the altitude table, a minimal valid Mermaid block per type, and expand/collapse rules, and EXAMPLES.md for worked LLDs.

Question loop

Unresolved decisions go to grill-me and nowhere else. There is no controlled LLD questionnaire and no lld domain in the count-based router of 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 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 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/<feature-name>-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.
• A map of the code as it is today, extracted mechanically → understand-codebase. 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, 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 — the HLD/LLD altitude table, traceability contract, Mermaid cheat-sheet, interface conventions, collapse rules, and document shapes.
• EXAMPLES.md — worked LLDs.
• templates/lld.md — the LLD skeleton.
• LLD contract — 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 — normative prose rules and the pre-save self-check for every human-read artifact this skill produces.
• design principles — 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.