hld-generate

HLD Generator

Generate a complete High Level Design document from a previously gathered context file. This skill runs with clean context and is non-interactive — all questions were answered during the gather phase.

Input

$ARGUMENTS — path to the context file (e.g., docs/context/hld/graphql-migration-context.md), and optionally --adr <path> for cross-referencing the predecessor ADR.

Parse Arguments

Extract from $ARGUMENTS:

• Context File: First non-flag argument
• ADR Path: --adr <path> (optional, for cross-referencing and back-reference updates)

Source Integrity Rules

Every factual claim in this document must be traceable to the context file.

1. Ground every claim. Every factual statement must trace back to a specific entry in the context file (user answers, codebase findings with file:line, or web research with URLs).
2. Flag ungrounded claims. If you need to state something not in the context file, mark it explicitly as [ASSUMPTION].
3. Never invent details. If the context file doesn't cover something, put it in Open Questions — don't fabricate.

Process

Step 1: Read Inputs

1. Read the context file from $ARGUMENTS.
2. If --adr provided, read the ADR for cross-referencing.
3. Read the HLD template at ${CLAUDE_SKILL_DIR}/references/template.md.

Extract from the context file:

• Problem statement and goals/non-goals
• User answers (scope, consumers, data entities, external systems, NFRs, deployment)
• ADR context (if applicable)
• Codebase findings with file:line citations
• Web research findings with URLs
• Change map (files to modify/create/delete, config changes, schema changes)
• Implementation phases
• Open questions

Step 2: Determine Output Path

1. If docs/ exists, propose docs/hld/<kebab-case-name>.md
2. If rfcs/ or designs/ exists, use that directory
3. Otherwise, propose docs/hld/<kebab-case-name>.md
4. Create the directory if needed.

Step 3: Generate the HLD

Write the complete HLD document section by section, following the template structure: