modules/claude-code: improve ai-docs skill

- Truncate and restructure for clarity
- Add followable workflow section with concrete NixOS example
- Add TDD principle
- Note negative framing OK when prohibiting

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: aster-void

modules/home/profile-dev/programs/claude-code/skills/ai-docs/SKILL.md

@@ -5,121 +5,79 @@ description: ALWAYS use this skill when writing AI documentation. Covers CLAUDE.
 
 # AI Documentation Skill
 
-## Research-Backed Principles (2024-2025)
-
-### What Works
-
-| Technique | Why | Source |
-|-----------|-----|--------|
-| **XML tags** | Claude trained on XML; improves parsing & structure | Anthropic docs |
-| **Templates with `{placeholders}`** | More reliable than prose instructions | Prompt engineering research |
-| **Concise + sufficient context** | >3000 tokens degrades reasoning | LLM length studies |
-| **Few-shot examples (1-3)** | Biggest gain is 0→1 example; diminishing returns after | Few-shot research |
-| **Positive framing** | "Do X" reduces ambiguity vs "Don't do X" | PromptHub studies |
-| **Explicit output format** | JSON/list/structure specification improves accuracy | Multiple studies |
-| **Task decomposition** | One prompt = one task | Overload research |
-
-### What Doesn't Work
-
-| Anti-Pattern | Problem | Research Finding |
-|--------------|---------|------------------|
-| **Vague prompts** | Forces AI to guess → generic output | Universal finding |
-| **Overloaded prompts** | Multiple tasks = quality degradation | Task complexity studies |
-| **Heavy persona prompting** | <10% variance explained for accuracy tasks | ACL 2024: Persona Effect |
-| **Long verbose prompts** | Recency bias; vaguer responses | Length impact studies |
-| **Negative instruction lists** | "Don't do X" underperforms "Do Y" | PromptHub research |
-| **Contradicting instructions** | Common in long system prompts | Best practices guides |
-
-### Claude-Specific
-
-- Claude weighs **user messages > system prompts** (unlike GPT)
-- XML tags like `<instructions>`, `<example>`, `<thinking>` are optimal
-- Nest tags for hierarchy: `<outer><inner></inner></outer>`
-- Be consistent with tag names; reference them in instructions
+## Core Principles
+
+| Do | Don't |
+|----|-------|
+| XML tags (`<rules>`, `<workflow>`) | Prose paragraphs |
+| Templates: `{placeholder}` | Vague instructions |
+| Positive: "Do X" | Negative: "Don't Y" (unless prohibiting) |
+| One task per prompt | Overloaded prompts |
+| Observable output | Internal instructions ("mentally X") |
+| Concrete examples | Abstract rules |
+| <3000 tokens | Long verbose docs |
+| TDD: tests first | Implementation first |
 
 ## Document Template
 
 ```markdown
-<settings>
-key = value
-</settings>
-
 <rules>
-1. [Rule]: [concrete example]
-   - `good example` not `bad example`
+1. [Rule]: `good` not `bad`
 </rules>
 
 <workflow>
-Template with {fill_in_placeholders}:
-- [Decision] {condition} → {action}
+1. {step with placeholder}
+2. [Decision] {cond} → {action}
 </workflow>
 
 <tools>
-tool-name = constraint or usage tip
+tool = gotcha or constraint
 </tools>
-
-<tips>
-- [Actionable tip with example]
-</tips>
 ```
 
 ## Writing Rules
 
-### Structure Over Prose
 ```
-BAD:  "You should try to keep your commit messages clear and descriptive"
-GOOD: Commit: `{scope}: {description}` (e.g., `modules/git: add hooks`)
+Structure:    BAD "keep commits clear" → GOOD `{scope}: {msg}`
+Positive:     BAD "Don't cd" → GOOD "Stay at repo root"
+Concrete:     BAD "reasonably sized" → GOOD "~100 lines"
+Observable:   BAD "mentally verify" → GOOD "output: Task, Constraints, Verify"
+Decision:     [Decision] simple → exec | complex → breakdown
 ```
 
-### Positive Over Negative
-```
-BAD:  "Don't use cd commands"
-GOOD: "Stay at repo root. Use relative/absolute paths."
-```
+## Followable Workflows
 
-### Concrete Over Abstract
-```
-BAD:  "Keep files reasonably sized"
-GOOD: "Target ~100 lines/file. Split when exceeding."
-```
+AI docs should include **step-by-step workflows** AI can mechanically follow.
 
-### Decision Markers
-```
-[Decision] simple task → execute | complex task → break down first
-[Decision] {condition} → {action A} | {otherwise} → {action B}
-```
+- Numbered steps, single action each
+- `[Decision] {cond} → {action}` for branches
+- `{placeholder}` for fill-ins
 
-## Content Guidelines
+example:
 
-**Include** (project-specific, non-obvious):
-- Conventions: commit format, file naming, directory rules
-- Constraints: "never X", "always Y before Z"
-- Decision templates with conditions
-- Tool-specific gotchas
+```markdown
+<workflow>
+## Adding a NixOS Module
+1. Create `modules/{home|nixos}/{name}/default.nix`
+2. Add option: `my.{name}.enable = lib.mkEnableOption "{name}";`
+3. [Decision] multiple configs → use collectFiles | single → inline
+4. Import in parent default.nix
+5. Verify: `nix flake check`
+</workflow>
+```
 
-**Exclude** (AI already knows or can find):
-- Generic best practices
-- Tool documentation
-- Code explanations (AI reads code)
-- Tutorials
+Anti-pattern: "Create appropriate module structure based on your judgment"
 
-## Length Guidelines
+## Content & Length
 
-| Document | Target | If Exceeded |
-|----------|--------|-------------|
-| CLAUDE.md | 50-150 lines | Split into skills |
-| Skills | 50-100 lines | Split into sub-skills |
-| Inline comments | 1 line | Rare exceptions for complex WHY |
+**Include:** conventions, constraints, decision templates, tool gotchas
+**Exclude:** generic best practices, tool docs, code explanations
 
-Reasoning: >3000 tokens measurably degrades LLM reasoning quality.
+| Doc | Lines |
+|-----|-------|
+| CLAUDE.md | 50-150 |
+| Skills | 50-100 |
 
 ## Checklist
 
-Before finalizing AI documentation:
-1. Using XML tags for structure?
-2. Templates have `{placeholder}` syntax?
-3. All instructions positive framing?
-4. Decision points marked with `[Decision]`?
-5. Concrete examples for every rule?
-6. Under length limit?
-7. No redundant info AI can infer?
+1. XML tags? 2. `{placeholders}`? 3. Positive framing? 4. `[Decision]` markers? 5. Examples? 6. Under limit?