Saved Prompts

# Homelab Adventures Blog - Content Guide

## Document Location
This document is located at: `~/stuff/gitrepos/wxs/prompts/hai.md`

## Overview

This guide covers content creation for Hugo static sites. The site supports multiple themes with easy switching between them.

### What I Need From You

Beyond technical implementation, I'm looking for your support with:
- **Naming** — Section names, titles, labels that sound right for a DevOps/platform engineer blog
- **Wording/Rephrasing** — Making content clear, engaging, and authentic
- **UX thinking** — Layout decisions, navigation flow, what feels right for readers

Think like a senior DevOps blogger when suggesting names and phrasing. Keep it professional but not corporate, technical but accessible.

### Content Restrictions

Some apps you don't want publicly documented — when listing apps or examples, skip these and use other services instead.

**Never link to private git host** - our Forgejo instance is not public. If you need to reference code/configs, include the relevant snippets inline instead.

**Anonymize internal domains** - Replace `*.wxs.ro` domains with `*.example.com` in code examples and configs. Exception: `hai.wxs.ro` is public and can be referenced.

### TODO Page

When the user asks to "add to TODO", add to `content/todo.md` (draft page, view with `hugo server -D`).

### Available Themes

| Theme | Description | Status |
|-------|-------------|--------|
| Hextra | Modern Tailwind-based theme inspired by Nextra, FlexSearch, diagrams | **Production (default)** |
| Lotus Docs | Technical documentation theme with search, dark mode, Mermaid, KaTeX | Available |

---

## Theme Switching

The site uses Hugo's environment-based configuration for theme switching.

### Config Structure

config/
├── _default/
│   └── hugo.yaml      # Default config (Hextra = production)
├── lotus/
│   └── hugo.yaml      # Lotus Docs theme config
└── hextra/
    └── hugo.yaml      # Hextra theme config

### Commands

# Production build (uses _default = Hextra)
hugo --minify

# Local development with specific theme
hugo server --environment lotus     # Lotus Docs
hugo server --environment hextra    # Hextra

---

## Content Structure

### Directory Layout

content/
├── _index.md                  # Site homepage (cascade: type: docs)
├── infrastructure/            # Content sections
│   ├── _index.md              # Section index
│   └── building-this-blog.md  # Individual post
├── crossplane/
├── tutorials/
├── custom-tools/
├── ai-tooling/
├── decisions/
├── recommended/
└── about/

### Current Sections

| Section | Weight | Purpose |
|---------|--------|---------|
| infrastructure | 100 | Homelab stack, hardware, services |
| crossplane | 150 | Crossplane compositions and IaC |
| tutorials | 200 | Step-by-step guides and how-tos |
| custom-tools | 250 | Tools I've built (s3bkp, kcl-ci, etc.) |
| ai-stuff | 350 | Claude Code, MCP integrations |
| decisions | 400 | ADRs - architectural decision records |
| recommended | 475 | Curated links, tools, resources |
| about | 500 | About page |

### Creating Content

**After creating a new page:** Search for existing pages that mention the topic and add internal links to the new page. This improves discoverability and connects related content.

### RSS Feed Configuration

**IMPORTANT:** When adding or removing content sections, update the RSS sections list in `config/_default/hugo.yaml`. The RSS feed only includes pages from sections listed there.

---

## Front Matter

### Required Fields

title: "Post Title"
description: "Brief description for SEO and navigation"
date: 2024-01-15
draft: false

### All Available Fields

title: "Complete Example"
description: "All front matter options demonstrated"
date: 2024-01-15
lastmod: 2024-01-16
draft: false
weight: 100              # Lower = higher in navigation (100, 200, 300...)
icon: "rocket_launch"    # Material icon name
toc: true                # Enable table of contents
tags: ["tag1", "tag2"]
katex: true              # Enable math rendering (only if needed)

### Weight Guidelines

- Use increments of 100 for easy reordering: 100, 200, 300
- Section `_index.md` files control section order
- Lower weight = appears first in navigation
- **Important**: Hextra sorts alphabetically by default. For weight-based sorting to work correctly, ALL pages in a section need weights set - not just some of them.

### Tags

When creating a new page:
1. **Check existing tags** by searching `content/` for `tags:` patterns
2. **Reuse existing tags** where they match (consistency over creativity)
3. **Propose new tags** only when needed
4. **Ask the user** to confirm the proposed tags before adding them

Keep tags lowercase, short, and meaningful. Avoid generic tags like "blog", "update", "milestone".

---

## Icons

Lotus Docs uses [Material Symbols](https://fonts.google.com/icons). Common icons:

| Icon Name | Use Case |
|-----------|----------|
| `article` | General documentation |
| `rocket_launch` | Getting started, quickstart |
| `settings` | Configuration |
| `code` | Code-related content |
| `dns` | Networking, infrastructure |
| `storage` | Storage, databases |
| `security` | Security topics |
| `build` | CI/CD, automation |
| `cloud` | Cloud services |
| `terminal` | CLI, commands |
| `hub` | Integrations |
| `description` | Guides, tutorials |

---

## Mermaid Diagrams

Mermaid diagrams render automatically in fenced code blocks (use language: mermaid).

### Mermaid Inside Tabs (Hextra)

**Limitation:** Mermaid diagrams only work in the **first tab** (visible on page load). Diagrams in hidden tabs won't render because mermaid.js can't calculate dimensions for hidden elements.

**Workaround:** Put mermaid diagrams in the first tab or outside the tabs entirely.

Supports: flowcharts (graph LR/TD), sequence diagrams, state diagrams.

---

## Alerts / Callouts

Use the `alert` shortcode for callouts:

### Contexts

alert context="info" text="Informational message"
alert context="success" text="Success message"
alert context="warning" text="Warning message"
alert context="danger" text="Error/danger message"
alert context="primary" text="Primary theme color"

### With Custom Emoji

alert icon="🚀" context="info" text="Custom icon alert"

### Multi-line with Markdown

alert context="info" with markdown content (bold, lists, etc.)

---

## Expandable Content (Details)

Use the `details` shortcode for collapsible sections — great for long code snippets, full prompts, or PRDs that would clutter the page.

details title="Click to expand full prompt" closed="true"
  Content here (markdown, code blocks, etc.)
/details

**When to use:**
- Full prompts or PRDs (show summary, hide full content)
- Long code examples
- Optional/advanced content that most readers can skip

**Prefer this over raw HTML `<details>`** — the Hextra shortcode has better styling and visibility.

---

## Code Blocks

Use fenced code blocks with language identifier for syntax highlighting.
Supports line numbers and line highlighting with Hugo options.

---

## Directory Tree Display

Use `treeview` language for directory structures.

---

## Best Practices

### Content Organization

1. **Use topic folders** for related content (infrastructure/, guides/, etc.)
2. **Keep URLs clean** - use lowercase, hyphens: `my-cool-post.md`
3. **Always add descriptions** - used in navigation and SEO
4. **Set meaningful weights** - controls navigation order

### Writing Style

1. **Use first person singular** - This is a personal blog. Use "I" and "me", not "we" and "us". Exception: prompt templates can use "we" when showing what to say to Claude.
2. **Front-load important info** - key points first
3. **Use headings liberally** - enables table of contents
4. **Include code examples** - practical over theoretical
5. **Add diagrams** - Mermaid for architecture/flows
6. **Simplify code snippets for readability** - Use cleaned-up simplified versions. Strip out noise like error handling, verbose comments, auth tokens. Readers want to understand the approach, not copy-paste production code.

### Content Objectives

When writing a page, guide the reader through these questions:

1. **What problem are we solving?** — The pain point, the frustration, the gap
2. **What tool are we using?** — Introduce the solution
3. **Why this tool?** — What makes it the right choice over alternatives
4. **How do we use it?** — Practical implementation, config, commands
5. **What's the end result?** — The outcome, the benefit, what success looks like

Not every page needs all five (quick tips might skip "why this tool"), but substantial content should address them.

### Images

Store in `static/images/` and reference as: `![Alt text](/images/my-image.png)`

### Internal Links

[Link to other post](ref "docs/other-post")
[Link with anchor](ref "docs/other-post#section")

---

## Local Development

Commands:
- `hugo server -D` — Start dev server with drafts
- `hugo --minify` — Build for production
- `devbox run -- hugo server -D` — With devbox

---

## Validation Checklist

Before publishing, verify:
- [ ] Front matter has title, description, date, draft: false
- [ ] Weight is set for proper navigation order
- [ ] Mermaid diagrams render correctly
- [ ] Code blocks have correct language specified
- [ ] All internal links work
- [ ] Images load properly
- [ ] Table of contents generates from headings
- [ ] Search indexes the content (check after deploy)
- [ ] Dark mode displays correctly

---

## Reference

### General
- [Hugo Documentation](https://gohugo.io/documentation/)
- [Mermaid Diagram Syntax](https://mermaid.js.org/syntax/flowchart.html)

### Theme-specific
- [Lotus Docs Documentation](https://lotusdocs.dev)
- [Lotus Docs Icons (Material Symbols)](https://fonts.google.com/icons)
- [Hextra Documentation](https://imfing.github.io/hextra/docs/)
- [Hextra Configuration](https://imfing.github.io/hextra/docs/guide/configuration/)

# Reflect Skill

Analyze the current conversation and propose improvements to skills based on what worked, what didn't, and edge cases discovered.

## Trigger

Run `/reflect` or `/reflect [skill-name]` after a session where you used a skill.

## Workflow

### Step 1: Identify the Skill

**Auto-detection**: Scan the conversation for skill invocations by looking for:
- `<command-name>/dot-ai:skill-name (MCP)</command-name>` tags (skill invoked via MCP)
- `<command-name>/skill-name</command-name>` tags (skill invoked locally)
- Skill file reads from `~/stuff/gitrepos/wxs/prompts/[skill-name].md`

If multiple skills were used, list them and ask which to analyze.

If no skills detected and skill name not provided, ask:

Which skill should I analyze this session for?
- [list skills from prompts repo]
- [other]

### Step 2: Analyze the Conversation

Look for these signals in the current conversation:

**Corrections** (HIGH confidence):
- User said "no", "not like that", "I meant..."
- User explicitly corrected output
- User asked for changes immediately after generation

**Successes** (MEDIUM confidence):
- User said "perfect", "great", "yes", "exactly"
- User accepted output without modification
- User built on top of the output

**Edge Cases** (MEDIUM confidence):
- Questions the skill didn't anticipate
- Scenarios requiring workarounds
- Features user asked for that weren't covered

**Preferences** (accumulate over sessions):
- Repeated patterns in user choices
- Style preferences shown implicitly
- Tool/framework preferences

### Step 3: Propose Changes

Present findings:

┌─ Skill Reflection: [skill-name] ──────────────────────────────┐
│                                                               │
│  Signals: X corrections, Y successes                          │
│                                                               │
│  Proposed changes:                                            │
│                                                               │
│  🔴 [HIGH] + Add constraint: "[specific constraint]"          │
│  🟡 [MED]  + Add preference: "[specific preference]"          │
│  🔵 [LOW]  ~ Note for review: "[observation]"                 │
│                                                               │
│  Commit: "[skill]: [summary of changes]"                      │
│                                                               │
└───────────────────────────────────────────────────────────────┘

Apply these changes? [Y/n] or describe tweaks

**Accessible Color Palette** (use ANSI codes in terminal output):

- HIGH: `\033[1;31m` (bold red #FF6B6B - 4.5:1 on dark)
- MED: `\033[1;33m` (bold yellow #FFE066 - 4.8:1 on dark)
- LOW: `\033[1;36m` (bold cyan #6BC5FF - 4.6:1 on dark)
- Reset: `\033[0m`

Avoid: pure red (#FF0000) on black, green on red (colorblind users)

- **Y** — Apply changes, commit, and push
- **n** — Skip this update
- Or describe any tweaks to the proposed changes

### Step 4: If Approved

1. Read the current skill file from `~/stuff/gitrepos/wxs/prompts/[skill-name].md`
2. Apply the changes using the Edit tool
3. Run git commands:
   cd ~/stuff/gitrepos/wxs/prompts
   git add [skill-name].md
   git commit -m "[skill]: [change summary]"
   git push origin main
4. Confirm: "Skill updated and pushed to Git"

### Step 5: If No Improvements Found

If the conversation analysis reveals no corrections, edge cases, or actionable signals:

> "No improvements identified for [skill-name]. The skill performed well in this session with no corrections needed."

Skip the proposal step and end the reflection.

### Step 6: If Declined

Acknowledge and end the reflection:

> "Understood. No changes made to [skill-name]."

## Git Integration

This skill has permission to:
- Read skill files from `~/stuff/gitrepos/wxs/prompts/`
- Edit skill files (with user approval)
- Run `git add`, `git commit`, `git push` in the prompts directory

## Example Session

User runs `/reflect frontend-design` after a UI session:

┌─ Skill Reflection: frontend-design ───────────────────────────┐
│                                                               │
│  Signals: 2 corrections, 3 successes                          │
│                                                               │
│  Proposed changes:                                            │
│                                                               │
│  🔴 [HIGH] + Constraints/NEVER:                               │
│            "Use gradients unless explicitly requested"        │
│                                                               │
│  🔴 [HIGH] + Color & Theme:                                   │
│            "Dark backgrounds: use #000, not #1a1a1a"          │
│                                                               │
│  🟡 [MED]  + Layout:                                          │
│            "Prefer CSS Grid for card layouts"                 │
│                                                               │
│  Commit: "frontend-design: no gradients, #000 dark"           │
│                                                               │
└───────────────────────────────────────────────────────────────┘

Apply these changes? [Y/n] or describe tweaks

## Important Notes

- Always show the exact changes before applying
- Never modify skills without explicit user approval
- Commit messages should be concise and descriptive
- Push only after successful commit