| name | tdk-epic-hld |
| description | Turn epic PRD artifacts into parent high-level design context before /tdk-task-breakdown. Use after /tdk-epic-prd; child specs do not run HLD by default. |
| metadata | {"version":"1.0.0"} |
tdk-epic-hld
Produce parent epic high-level design (HLD) artifacts from /tdk-epic-prd
output before /tdk-task-breakdown.
User Input
$ARGUMENTS
Trigger: /tdk-epic-hld <epic-id> [--force]
--force skips the duplicate-directory prompt and takes the overwrite path.
It never bypasses the epic PRD readiness gates.
Boundary Declaration
This command produces:
- Epic dashboard update at
{FEATURE_DIR}/index.md
- HLD stage manifest at
{FEATURE_DIR}/high-level-design.md
- Five detail artifacts under
{FEATURE_DIR}/high-level-design/: requirement-overview.md, project-and-technical-overview.md, data-flow.md, screen-flow.md, decisions-and-risks.md
This command does NOT:
- Create child
spec.md files (use /tdk-specify from task-breakdown seeds)
- Create implementation plans (use
/tdk-plan on a clarified child spec)
- Implement code (use
/tdk-implement)
- Create portable child spec seeds (use
/tdk-task-breakdown)
- Create GitHub, GitLab, Backlog, or other tracker issues, or call tracker APIs/CLIs
- Mint
UR-*, FR-*, SC-*, or FS-* identifiers
HLD is parent epic design context for safe decomposition. Child specs are the
requirement authority and do not run HLD by default.
Skill References
Load before generating any artifact:
references/high-level-design-output-contract.mdreferences/high-level-design-lenses.mdreferences/high-level-design-skill-routing.md
Execution Steps
Step 0 - Validate Epic ID
Invoke tdk-validate-task-id with $ARGUMENTS and host skill name /tdk-epic-hld.
If STOP, halt execution.
Store: TASK_ID, TASK_ID_SOURCE.
Step 0.1 - Load Project Context
Invoke tdk-load-project-context with validated TASK_ID.
Store: PROJECT_CONTEXT, FEATURE_DIR.
Step 1 - Read Epic PRD
Require and read exactly these parent epic PRD artifacts:
{FEATURE_DIR}/epic-prd.md
{FEATURE_DIR}/epic-prd/prd.md
{FEATURE_DIR}/epic-prd/slice-map.md
{FEATURE_DIR}/epic-prd/open-questions.md
If any file is missing, STOP before writing and tell the user to run
/tdk-epic-prd {TASK_ID} first.
Step 2 - Epic PRD Readiness Gates
STOP before writing any file when:
epic-prd/open-questions.md has any item under ## Blocking Questions.epic-prd/slice-map.md has no independently specifiable slice.epic-prd/slice-map.md contains catch-all slices such as "all features",
"entire MVP", or "whole epic".
These gates are never bypassable. --force does not override them.
Step 3 - Load Output Contract
Read references/high-level-design-output-contract.md from this skill directory.
Use that reference as the single source of truth for:
- Output filenames and directory
high-level-design.md schema and per-artifact section schemas- Epic PRD source mapping
- Slice-boundary and breakdown-readiness rules
- Requirement-authority rules
Step 3.1 - Load Built-In HLD Lenses
Read references/high-level-design-lenses.md from this skill directory.
Use the built-in lenses to enrich parent epic design with slice boundaries,
quality attributes, security posture, data/API assumptions, user journey
touchpoints, and operability concerns. Lens findings may become assumptions,
risks, decisions, or follow-ups only.
Step 3.2 - Load Optional HLD Skill Routing
Read references/high-level-design-skill-routing.md from this skill directory.
Resolve optional project routing from:
{PROJECT_CONTEXT.docs.path}/custom-workflow/high-level-design-skill-routing.md
The missing HLD routing file is non-blocking; continue with built-in lenses when
it does not exist.
When routing exists, read matching consumer SKILL.md files as advisory design
lenses. Consumer HLD skills are advisory only: they may provide design notes,
risks, assumptions, or questions, but they must not write files, create
requirement IDs, invoke implementation skills, or change status.
Do not create ## Delegate Skills in any HLD artifact. Do not write outside the
six contracted HLD artifacts.
Step 4 - Extract Parent Design Context
From epic PRD artifacts, extract:
- product objective and scope boundaries from
prd.md
- slice keys, boundaries, dependencies, and child spec seeds from
slice-map.md
- blocking/non-blocking ambiguity from
open-questions.md
- source discovery links from
epic-prd.md
Do not invent file paths, APIs, database tables, owners, estimates, labels, or
formal requirement IDs. If the PRD or slice map is too vague for decomposition,
STOP and tell the user to rerun /tdk-epic-prd {TASK_ID} --interview or update
the epic PRD.
Step 5 - Generate Artifacts
Generate the six artifacts from the templates under
.specify/templates/high-level-design/, following the contract:
- Use epic PRD slice keys and source artifact references for traceability.
- Do not cite or mint
UR-*, FR-*, SC-*, or FS-*.
- Optimize output for
/tdk-task-breakdown: slice boundaries, dependencies,
interfaces, data/user flow assumptions, design risks, and child spec seed
impact.
- Fold lens and advisory consumer findings into existing artifact sections as
assumptions, risks, decisions, or follow-ups only.
- Text-first; Mermaid optional.
Step 6 - Duplicate Directory Handling
If high-level-design/index.md exists and sibling high-level-design.md is
missing, STOP with:
legacy layout detected: high-level-design/index.md is from the old nested-manifest layout. Re-run with --force to regenerate HLD in the new layout, or recreate the test epic. TDK does not auto-migrate old high-level-design/index.md content.
If {FEATURE_DIR}/high-level-design.md or {FEATURE_DIR}/high-level-design/ already exists:
- Without
--force: ask the user (AskUserQuestion) whether to update or overwrite.
- update = regenerate the skill-generated artifacts in place; do NOT delete the directory; preserve user-edited and non-generated files.
- overwrite = delete the stage manifest and directory, then fully regenerate.
- With
--force: skip the prompt and take the overwrite path.
The Step 2 gates still run first regardless of --force.
Step 6.5 - Update Epic Dashboard
Update the generated HLD section in {FEATURE_DIR}/index.md. Link the
high-level-design.md stage manifest, summarize readiness, and show the next
command: /tdk-task-breakdown {TASK_ID}. Preserve user-owned content outside
generated sections. Replace an existing generated HLD section only after
confirmation or when --force is supplied.
Step 7 - Report Results
Report:
- Relative paths for
{FEATURE_DIR}/index.md, high-level-design.md, and each detail artifact written
- Whether update or overwrite was taken (when the directory pre-existed)
- Readiness for
/tdk-task-breakdown {TASK_ID}
Step 8 - Recommend Next Step
Use AskUserQuestion with header "Next Step" after reporting results:
| Option | Action |
|---|
/tdk-task-breakdown {TASK_ID} (Recommended) | Invoke /tdk-task-breakdown {TASK_ID} |
/tdk-epic-hld {TASK_ID} --force | Invoke /tdk-epic-hld {TASK_ID} --force only when the user wants to regenerate the HLD artifacts |
| End session | Stop |
Quality Gates
