homelab-ai-agent/docs/templates/doc-generation-prompt.md

Ready-to-Use AI Prompt — Homelab Documentation Generation

Use this prompt when asking Grace (or any AI agent) to create or update documentation for a homelab module or stack. Copy the relevant block, fill in the placeholders, and send.

---

PROMPT A — Generate a new MODULE doc from scratch

You are documenting a homelab module. Use the template at:
  docs/templates/module-doc-template.md
Follow all rules in:
  docs/templates/module-doc-rules.md

Module name: {{module_name}}
Repo: {{repo_name}}

Here is what I know about this module:
{{paste known facts: purpose, install steps, config, connections, dependencies, etc.}}

Instructions:
1. Read the template and rules files from the repo before writing anything.
2. Fill every section of the template using the information provided above.
3. For sections where information is missing, insert a clear placeholder comment:
   <!-- TODO: fill in {{section_name}} -->
4. All commands must be in code blocks.
5. Mark credentials as: "stored in Infisical as {{SECRET_NAME}}" — never hardcode values.
6. In the Connections section, describe where this module sits in the full stack.
7. In the References section, flag any external docs not yet in RAG with:
   AI TODO: Schedule RAG import for <doc name>.
8. Add a Change Log entry: {{YYYY-MM-DD}} | Added | Initial draft
9. Save the completed doc to: docs/{{module_name}}.md in the {{repo_name}} repo.
10. Commit and push. Confirm when done.

---

PROMPT B — Generate a new STACK doc from scratch

You are documenting a homelab stack. Use the template at:
  docs/templates/stack-overview-template.md

Stack name: {{stack_name}}
Repo: {{repo_name}}

Here is what I know about this stack:
{{paste known facts: purpose, components, config, connections, dependencies, etc.}}

Instructions:
1. Read the template file from the repo before writing anything.
2. Fill every section of the template using the information provided above.
3. For sections where information is missing, insert a clear placeholder comment:
   <!-- TODO: fill in {{section_name}} -->
4. All commands must be in code blocks.
5. Mark credentials as: "stored in Infisical as {{SECRET_NAME}}" — never hardcode values.
6. In the Connections section, describe how this stack interacts with ALL other stacks
   and external systems in the homelab. Be explicit about data flow direction.
7. In the References section, flag any external docs not yet in RAG with:
   AI TODO: Schedule RAG import for <doc name>.
8. Add a Change Log entry: {{YYYY-MM-DD}} | Added | Initial draft
9. Save the completed doc to: docs/{{stack_name}}-stack.md in the {{repo_name}} repo.
10. Commit and push. Confirm when done.

---

PROMPT C — Update an EXISTING doc (module or stack)

You are updating an existing homelab documentation file.

File: docs/{{filename}}.md in repo {{repo_name}}
Sections to update: {{list sections: e.g. Configuration, Connections, Change Log}}

Changes to make:
{{describe what changed: new config options, new connections, bug fixes, etc.}}

Rules:
1. Read the current file before making any changes.
2. Do NOT delete any existing content unless I explicitly say so.
3. Append new content — never overwrite.
4. Match the existing style and formatting exactly.
5. Only touch the sections listed above.
6. Add a Change Log entry: {{YYYY-MM-DD}} | Updated | {{brief summary}}
7. Return only the updated sections with their AI GENERATED markers.
8. After I confirm, save the full updated file, commit, and push.

---

PROMPT D — Audit an existing doc for completeness

Audit the documentation file: docs/{{filename}}.md in repo {{repo_name}}

Check each section against the template (docs/templates/module-doc-template.md
or stack-overview-template.md as appropriate):

1. Are any sections missing or still showing template placeholders?
2. Are credentials hardcoded anywhere (should be Infisical references)?
3. Are there external docs in References not yet flagged for RAG import?
4. Is the Change Log up to date?
5. Are Connections complete — does it describe where this module/stack sits in the full homelab?

Report findings as a list. Do not make changes yet — wait for my confirmation.

---

Notes

• Templates live in docs/templates/ in every active repo.
• Secrets always reference Infisical — never hardcode.
• External docs not yet in RAG always get flagged with AI TODO: Schedule RAG import.
• Change Log entries always append — never delete previous entries.
• When in doubt: append, don't replace.