technical-proposal-crafting

Technical Proposal Skill

Write, review, and edit design proposals that drive alignment (HLD) and guide implementation (LLD).

When using this skill, begin by stating: "I'm using the technical-proposal-crafting skill, which enforces: right altitude for the audience, a narrative that builds a case rather than filing a report, each fact stated once, explicit status tagging (IMPLEMENTED/WIRING-ONLY/NET-NEW), and confident voice throughout."

Context: This skill covers writing, reviewing, and editing both High-Level and Low-Level design proposals across any domain. For document-type specifics, read references/hld.md and references/lld.md. For the discipline of grounding claims, read references/claim-grounding.md. Read references on demand.

Core Principles

1. Pick the right altitude first. HLD ≠ LLD ≠ both-in-one. An HLD aligns stakeholders on boundaries, contracts, and decisions; an LLD documents mechanics for implementers. Mixing them produces a doc that is too detailed for approvers and too vague for engineers. Decide which you're writing (or write both, cleanly separated) before drafting. See references/hld.md / references/lld.md.
2. Build a case, not a report. The document should read as a logical progression: here is the problem, here is the solution, here is why it works. Each section should earn its place by advancing the argument, not by checking a structural box. If a section's content would be equally true in any order, the narrative has no arc.
3. State each fact once. If a fact needs to appear in two sections, one of those sections has a structural problem. Restate it once (in the most authoritative location) and rely on the reader's memory for the rest. Repetition signals the author didn't trust the document's structure — and signals an AI generator padding for completeness.
4. Write confidently. An HLD should only be written once key decisions are settled. Hedged language — "should be confirmed by X," "may need to revisit" — signals the document is premature. Resolve the open questions first. If a scope boundary genuinely can't be resolved at HLD time, state it explicitly as a non-goal or downstream concern; don't leave it as an inline hedge.
5. Ground load-bearing claims in verifiable sources. A design that asserts "component X exposes port Y / requires permission Z / already does W" must be checkable against code, config, or a cited doc. Ungrounded specifics are a common cause of proposals that pass review and then fail in implementation. See references/claim-grounding.md.
6. Tag implemented and proposed; don't rely on tense. Mark every behavioral claim explicitly: IMPLEMENTED (in source today), WIRING-ONLY (needs config/flag), NET-NEW (must be built). Tense is a readability choice; it does not reliably distinguish what exists from what must be built. See references/claim-grounding.md.
7. No fact drift across linked documents. When an HLD points to an LLD, a fact stated in both must match exactly. Correct a claim in one place and the contradiction is a defect. Keep numbers, names, and permissions single-sourced.
8. State what you deliberately did NOT do. Non-goals prevent re-litigating settled questions. Rejected alternatives are optional (an appendix is the right home) — but scope boundaries belong in the HLD body.
9. Write for the document's actual audience. An HLD a PM cannot follow has failed regardless of technical merit. An LLD that hand-waves the mechanics has failed the engineer. Match vocabulary and depth to who must act on the doc.