docs(aidd-context): keep skill instructions readable and coherent - #981

🎯 What & why

Make generated skills easier to scan and keep instruction changes coherent. Apply the same guidance to skill-authoring.md:7 itself.

🛠️ How it works

• R20, new rule: “Write for scanning.”
  • “Keep sentences short, with one idea each.”
  • “Keep short, closely related instructions together.”
  • “Use sub-items only when they improve readability.”
• R17, two instructions added to “One fact, one home.”
  • “Before adding or changing an instruction, check the whole skill for overlap or conflict.”
  • “Resolve overlaps and conflicts by proposing a coherent revision of the owning rule.”
• R18, content references by purpose added.
  • “Identify content to read or edit by its purpose.”
  • “Do not depend on line numbers, exact headings, or quoted anchors.”
  • “Keep exact names when required by the artifact's format.”
• R5, language preference clarified.
  • “Prefer English unless the user specifies another language.”
  • Its existing “one idea per sentence” requirement moves to R20, avoiding duplication.
• R1–R4, R6–R16, and R19, presentation changes.
  • Rephrase and split dense rules into clearer sub-items, retaining their identifiers and existing requirements.
  • Keep short related clauses together, as in R1: “Keep one domain per skill, named per naming.md.”

🧪 How to verify

• pnpm exec lefthook run pre-commit
• node scripts/check-architecture-rules.js plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md
• git diff --check

✅ I certify

• I DO CERTIFY I READ EACH LINE OF THE PULL REQUEST BECAUSE I AM A SOFTWARE ENGINEER, NOT A AI PUPPY.