---
name: hla
description: Use when the user wants to generate the F1 high-level architecture from Discovery proposal and indexed RF/RNF. Reads docs/discovery/<project-slug>/inputs/business-proposal.md and requirements/index.json, then writes docs/discovery/<project-slug>/hla/hla.md. Triggers on "/machine-discovery:hla <project-slug>", "/hla <project-slug>", and requests for Discovery HLA.
---

# HLA

Generate the F1 high-level architecture artifact from the Discovery proposal and indexed requirements.

## Inputs

```text
docs/discovery/<project-slug>/inputs/business-proposal.md
docs/discovery/<project-slug>/requirements/index.json
docs/discovery/<project-slug>/requirements/requirements.md
docs/discovery/<project-slug>/requirements/items/RF-###.md
docs/discovery/<project-slug>/requirements/items/RNF-###.md
```

## Output

```text
docs/discovery/<project-slug>/hla/hla.md
```

## Operating protocol

1. Parse `$ARGUMENTS` and resolve the output language.
   - The first token MUST be a kebab-case ASCII project slug.
   - A second token MAY be `es` or `en`; if present, it wins.
   - If a second token is present and is not `es` or `en`, stop with `NEEDS INPUT: language must be es or en`.
   - If no language argument is present, inherit `language` from `requirements/requirements.md`; otherwise from `inputs/business-proposal.md`; if missing, use the current user request language; if ambiguous, default to `es`.
   - If missing or invalid, stop with `NEEDS INPUT: indica el project slug, por ejemplo /machine-discovery:hla acme-demo`.
2. Validate prerequisites:
   - Business proposal exists and is non-empty.
   - `requirements/index.json` exists and has at least one requirement.
   - `requirements/requirements.md` exists and is non-empty.
   - Every indexed item requirement Markdown file exists and is readable.
3. If `hla/hla.md` already exists, ask before overwriting. Do not silently replace it.
4. Write `docs/discovery/<project-slug>/hla/hla.blocks`.
   - The content file MUST contain one `@@KEY@@` block for each placeholder in `templates/hla.<lang>.md.tmpl`, including `@@LANG@@`.
   - Fill every content block from evidenced proposal and requirement content.
   - `@@TECH_STACK@@`: propose languages, frameworks, datastores, and tooling, each WITH a one-line justification. When a choice is not evidenced, propose a reasonable default and mark it `NEEDS INPUT: confirm <choice> with architect/TL` — do NOT present it as a final decision.
   - `@@COMPONENT_DIAGRAM@@`: a Mermaid graph (e.g. `graph TD`) of the main components and their relations. It is inserted inside a ```mermaid fence in the template, so emit ONLY the Mermaid body (no fence lines).
   - `@@DEPLOYMENT_MODEL@@`: target infrastructure, environments (dev/staging/prod), and deployment strategy. Unknown parts → `NEEDS INPUT`.
   - `@@TECHNICAL_RISKS@@`: one entry per risk, each stating an impact level (`Alta|Media|Baja` / `High|Medium|Low`) and a proposed mitigation.
5. Unknown architecture decisions MUST be written as `NEEDS INPUT: <specific question>`.
6. Run `bash plugins/machine-discovery/scripts/assemble-doc.sh plugins/machine-discovery/skills/hla/templates/hla.<lang>.md.tmpl docs/discovery/<project-slug>/hla/hla.blocks docs/discovery/<project-slug>/hla/hla.md`.
7. Delete `hla.blocks` only after validating the assembled Markdown.
8. Score against [references/checklist.md](references/checklist.md). Pass criterion: 7/7. Fix and re-render any failed item.
9. Final report MUST print exactly `/machine-discovery:planning <project-slug>` as the next-step suggestion. Do not run it.

## Hard rules

- **Requirements required.** Do not generate HLA without `requirements/index.json`.
- **Traceability required.** Every capability or constraint in HLA MUST cite RF/RNF IDs.
- **Stack proposed, not fabricated.** The HLA MUST propose a technology stack (languages, frameworks, datastores, tooling) with a one-line justification each. Choices not evidenced MUST be marked `NEEDS INPUT: confirm with architect/TL`, not presented as final. Never invent client-specific facts (existing systems, credentials, contractual constraints).
- **Component diagram required.** The component-diagram section MUST contain a Mermaid graph of the main components and their relations.
- **Risks carry impact + mitigation.** Every technical risk MUST state an impact level and a proposed mitigation.
- **Script-owned Markdown.** Final HLA Markdown MUST be assembled by `scripts/assemble-doc.sh` from `.blocks` and template.
- **Selected-language output.** Generated titles, body prose, and template-owned headings MUST match the resolved output language; verbatim source quotes stay unchanged.
- **No auto-chaining.** Do not run planning or PRD generation.
- **Namespaced next step.** Final user-facing next-step suggestion MUST be `/machine-discovery:planning <project-slug>`.

## References

- HLA templates: [templates/hla.es.md.tmpl](templates/hla.es.md.tmpl), [templates/hla.en.md.tmpl](templates/hla.en.md.tmpl)
- Quality checklist: [references/checklist.md](references/checklist.md)
- Anti-patterns: [references/anti-patterns.md](references/anti-patterns.md)