cli-forge-hld

Optimization: This skill uses on-demand loading. Heavy content lives in references/ and is loaded only when needed.

Language rule: Skill instructions are written in English. When generating user-facing output, detect the project's primary language (from README, comments, docs, commit messages) and produce the document in that language. If the project is bilingual, ask the user which language to use before proceeding.

Diacritics rule: When the chosen output language uses diacritics (French, Spanish, Portuguese, etc.), render them correctly — including on capitals (É, À, Ç, Ô…). Never strip accents to ASCII: write "sécurité" not "securite", "Rôle" not "Role". ASCII-flattened French is a defect, not a style.

Writing style: Favor clarity — short sentences, one idea per sentence, plain words. A metaphor only when it clarifies. Keep one consistent register (impersonal/infinitive for operational docs). Separate narrative prose, meant to make the reader understand, from telegraphic content (tables, commands, checklists) which stays terse for action.

No fabricated output: Never invent command output, console captures, API responses, metrics, or logs. When real output is needed, emit a clearly-marked placeholder (🚧 "replace with a real capture"), never plausible-but-fake text presented as real.

Forge HLD — High-Level System Design

"Everything is a trade-off. Why is more important than how." — Neal Ford & Mark Richards

Core Principles

1. Mitosis — the document grows only the sections the project actually needs. A CLI tool doesn't need a deployment diagram. A single-service app doesn't need a context map. Kill empty sections, don't fill them with boilerplate
2. Numbers before architecture — always estimate capacity before designing. The numbers determine whether you need 1 server or 100
3. Every decision needs a "why" — no technology choice without justification via ADR
4. Tradeoffs are explicit — use ATAM-style reasoning: "We chose X over Y because [quality attribute] matters more than [other attribute] in this context"
5. Diagrams are mandatory — use Mermaid for all visuals (C4, sequence, deployment)
6. Non-goals are as important as goals — they prevent scope creep (Google design doc tradition)
7. KISS — if a section can be one table instead of three paragraphs, use the table. If a diagram replaces a page of text, use the diagram. Readers scan, they don't read
8. Gotchas — read ../gotchas.md before producing output to avoid known mistakes