lld-docs

name	lld-docs
description	Use when generating, editing, or merging Low-Level Design (LLD) documents at `docs/lld/<component>.md` or `docs/shield/<feature>/lld-<component>.md`. Triggers on /lld command (Path A) and on /plan TRD-driven authoring (Path B, M2 plan). Owns the backend and infra templates, atomic write, provenance stamp, and §14 Changelog convention.

lld-docs

Author component-scoped Low-Level Design documents in one of two operational modes:

• draft — net-new component. Emit a fresh template (backend or infra per the resolved type), populate sections from the available context (PRD, research, TRD, repo evidence), and atomic-write to the target path.
• merge — enhancement of an existing canonical LLD. The caller has already copied docs/lld/<component>.md into the target draft path; this skill identifies which sections the current work affects, edits those sections in the draft, and leaves untouched sections verbatim.

Both modes preserve all 14 sections in canonical order (per shield/schema/lld-sections-<type>.yaml) and emit explicit {#kebab-case} anchors. The shared header metadata block precedes §1; the §14 Changelog row is the only mandatory addition on merge runs.

Template selection

type argument	Slug allow-list	Section template
backend	shield/schema/lld-sections-backend.yaml	lld-template-backend.md
infra	shield/schema/lld-sections-infra.yaml	lld-template-infra.md

type is required. It's resolved by the caller (the /lld command or /plan) before invoking this skill.

Output paths

Caller	Target path
/lld <component> (Path A)	docs/lld/<component>.md (canonical, direct)
/plan TRD-driven (Path B, M2 plan)	docs/shield/<feature>/lld-<component>.md (draft)

This skill does NOT promote drafts to the canonical path — that's /implement's job at milestone close (M2 plan, step 5h).

Atomic write contract

1. Compute the target path.
2. Write content to <target>.tmp.
3. Atomic-rename <target>.tmp → <target> via os.replace() (Python) or mv (shell).
4. On any failure between steps 2 and 3 (write error, signal interrupt), remove <target>.tmp and surface the error. Never leave a partial <target> behind.
5. Before the write, apply shield:writing-style to author-written prose sections (overview, rationale, narrative). Do NOT alter the provenance stamp, the §14 Changelog rows, header metadata, code blocks, or n/a — <reason> escapes.

When emitting Mermaid diagrams, follow shield/skills/general/mermaid-authoring.md (hard syntax rules — no semicolons, no reserved-word actors, balanced blocks).

Mermaid validation (before write)

Before the atomic write, validate every ```mermaid block:

1. Run python3 shield/scripts/validate_mermaid.py <target>.tmp (or validate the composed content). If it passes, proceed to the write.
2. If it fails, run python3 shield/scripts/validate_mermaid.py --fix <target>.tmp to repair the deterministic classes, then re-validate.
3. If findings remain, rewrite the offending diagram from the parse error, re-validate, and retry (bounded — 3 attempts). Never write a file whose diagrams do not validate.

Diagram syntax rules: shield/skills/general/mermaid-authoring.md.

Provenance stamp

The first line after the document's frontmatter (or after the H1, if no frontmatter is used) MUST be:

<!-- generated by /lld v{plugin-version} on {YYYY-MM-DD} -->

{plugin-version} is read from .claude-plugin/marketplace.json shield entry. {YYYY-MM-DD} is today's date in UTC.

Header metadata

Populate the header block (above §1) as follows:

Field	Source
Feature	The active feature folder slug if invoked by /plan; else "manual" (Path A).
Owner	git config user.email of the invoking user.
Status	draft (new) or unchanged (merge). /implement sets promoted on canonical promotion (M2 plan).
Linked PRD	Relative path from the LLD to the active feature folder's prd.md, if it exists; else "n/a".
Linked plans	List of relative paths to plan.md(s) — initialised to [<active plan>] for Path B; [] for Path A.
Version	0.1.0 for net-new; bump-patch on merge runs (e.g. 0.1.0 → 0.1.1).
Last updated	Today's date YYYY-MM-DD.

§14 Changelog row format

Every drafting or merge run appends one row to §14:

| <Touch> | <YYYY-MM-DD> | <Summary> | <Story IDs> |

Where:

• <Touch> = M<n> (Path B) or manual (Path A).
• <Summary> = one-line human-readable. For Path B, derives from the milestone name or the calling story's name. For Path A, takes the form "reverse-doc by <owner>" or "edit by <owner>".
• <Story IDs> = space-separated for Path B; n/a for Path A.

n/a — <reason> escape

Any section may declare n/a — <reason> when it genuinely doesn't apply. Vague TBDs (TBD, TODO, to be determined, etc.) in always-on sections cause the lld-docs eval to fail.

Promote-on-demand sections

Backend §9 + §11 and infra §7 + §11 default to collapsed <details> blocks:

<details>
<summary>§9 Configuration</summary>

(promote-on-demand — lift by replacing `<details>` with `<details open>` and
populating non-vague content)

</details>

Lift them only when the component's nature warrants it; an empty PoD section is fine, an open-but-vague PoD section is a finding (M3 plan).

Forced subsections

Backend §12 has 8 forced subsections; infra §12 has 6. Each MUST be present with non-vague content (or n/a — <reason>). The exact subsection list comes from shield/schema/lld-sections-<type>.yaml (forced_subsections key).

Invocation contract

Callers (M1: /lld command; M2: /plan) invoke this skill with:

Input	Required	Notes
component	yes	kebab-case identifier.
type	yes	backend or infra.
mode	yes	draft or merge.
target_path	yes	Absolute or repo-relative path.
context	no	Dict of {prd_path, trd_path, research_path, story_design_refs}; populated by Path B.

The skill returns:

• The number of sections populated (informational; not a contract).
• The §14 Changelog row that was appended.
• Any sections that declared n/a — <reason> (for the run summary).

Failure modes

Failure	Behavior
Target directory doesn't exist	Create it (mkdir -p).
<target>.tmp write fails	Remove .tmp; raise. Hard fail per design §8 row 8.
<target> already exists in draft mode	Caller's job to decide overwrite vs. abort. If caller passes mode=draft and target exists, default to edit-in-place + Changelog row append (Path A reverse-doc semantics); never silently clobber a populated file's content.
Section count after generation ≠ 14	Raise (template emitter bug).
Forced subsection count under §12 ≠ allow-list count	Raise (template emitter bug).