hads-convert

name	hads-convert
description	Convert any technical document (README, API docs, spec, wiki page) into valid HADS format. Triggers on "convert to HADS", "HADS this", "make this HADS-compatible", or any request to optimize a document for AI consumption.

HADS Convert Skill

Version 1.0.0 · hads-skills · 2026

---

AI READING INSTRUCTION

Read [SPEC] blocks for conversion rules. Read [BUG] blocks before writing any output. [NOTE] blocks explain intent — read if a rule is unclear.

---

1. TRIGGER

[SPEC] Activate when user:

• Says "convert to HADS", "HADS this", "make this HADS"
• Provides a document and asks to optimize for AI consumption
• Asks to restructure docs for token efficiency

[NOTE] Tokens are spent once at conversion. Every future AI read of the output is cheaper. This is the core value proposition — convert once, save on every subsequent call.

---

2. INPUT

[SPEC] Accept any of:

• File path → read the file contents
• Pasted text → use directly
• URL → fetch the page content

If input is ambiguous, ask: "File path, paste, or URL?"

---

3. CONVERSION RULES

[SPEC] Classify every piece of content before writing:

Source content	Output block
Fact, requirement, spec, API contract	**[SPEC]**
History, rationale, example, narrative	**[NOTE]**
Known bug, failure mode, gotcha, workaround	**[BUG] Title**
Unverified, assumed, inferred, "probably"	**[?]**

Rules:

• One block type per paragraph — do not mix
• [SPEC] content: bullet lists or tables, max 2 sentences prose
• [BUG] blocks must contain: symptom, cause, fix (all three)
• Do not invent content — only restructure what exists
• Do not duplicate content across block types

[NOTE] When in doubt between [SPEC] and [NOTE]: if a developer must know it to use the thing correctly, it's [SPEC]. If it explains why, it's [NOTE].

---

4. OUTPUT STRUCTURE

[SPEC] Write output in this exact order:

# [Original title or inferred title]
**Version [preserved or 1.0.0]** · [Author if known] · [Date: today] · HADS 1.0.0

---

## AI READING INSTRUCTION

Read `[SPEC]` and `[BUG]` blocks for authoritative facts.
Read `[NOTE]` only if additional context is needed.
`[?]` blocks are unverified — treat with lower confidence.

---

## 1. [Section]

**[SPEC]**
...

• Numbered H2 sections
• H3 for subsections
• Preserve original section grouping where logical
• Add changelog section at end if document has version history

---

5. OUTPUT DESTINATION

[SPEC]

• If input was a file: write to [original-name].hads.md (keep original intact)
• If input was pasted text: print output directly
• If user specifies path: use that path
• Always confirm: "Written to filename.hads.md"

---

6. POST-CONVERSION REPORT

[SPEC] After writing, report:

• Original line count vs HADS line count
• Block distribution: X [SPEC], Y [NOTE], Z [BUG], W [?]
• List any [?] blocks explicitly — user must verify these

[BUG] Silent data loss on dense prose

• Symptom: long narrative paragraphs get condensed into [SPEC] bullets, losing nuance
• Cause: over-aggressive summarization
• Fix: move dense narrative to [NOTE] intact, only extract verifiable facts into [SPEC]