From b47e1129ea1150a5ffde67d8cd9f8ed7bed7b29f Mon Sep 17 00:00:00 2001
From: Grace <grace@ubuntu-server-ai>
Date: Tue, 17 Mar 2026 16:25:09 -0700
Subject: [PATCH] Add ready-to-use AI doc generation prompt

---
 docs/templates/doc-generation-prompt.md | 118 ++++++++++++++++++++++++
 1 file changed, 118 insertions(+)
 create mode 100644 docs/templates/doc-generation-prompt.md

diff --git a/docs/templates/doc-generation-prompt.md b/docs/templates/doc-generation-prompt.md
new file mode 100644
index 0000000..a5e03c3
--- /dev/null
+++ b/docs/templates/doc-generation-prompt.md
@@ -0,0 +1,118 @@
+# 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.