{"key":"ai_change_documentation_spec","title":"ai-change-documentation-spec.md","content":"# AI Change Documentation Spec\n\nUse this document when an AI model is asked to document a completed or in-progress homelab change.\n\n## Purpose\n\nGenerate the documentation notes, change records, and related files needed to capture a homelab change in a way that is:\n- rebuild-useful\n- operationally clear\n- consistent with this repository\n- safe with respect to secrets\n\nThis file is intended to be referenced directly in prompts.\n\n## Prompt Pattern\n\nUse a prompt in this shape:\n\n```text\nAs per the AI Change Documentation Spec, create the documentation notes for what we changed here. If you need any missing facts, ask only the minimum necessary questions first. Then generate all required notes and files in the appropriate locations.\n```\n\n## Required Behavior\n\nWhen given a request to document a change, the model must:\n\n1. Identify the change scope.\n2. Determine whether enough facts are already available.\n3. Ask only the minimum missing questions required to document the change correctly.\n4. Generate the required documentation files in the repository structure.\n5. Avoid recording secrets.\n6. Prefer precise facts over vague summaries.\n7. Make the output useful both for future operations and rebuild scenarios.\n\n## Secret Handling Rules\n\nDo not document:\n- passwords\n- tokens\n- private keys\n- raw credential files\n- secret values from `.env` files\n- full database dumps\n\nDo document:\n- where secrets live\n- which system/service uses them\n- which config files or env files reference them\n- which paths, mounts, compose files, or services depend on them\n\n## Documentation Layers\n\nFor each significant change, decide what belongs in:\n\n### 1. Current-state documentation\n\nUse this when the change affects the current operating state of the homelab.\n\nExamples:\n- hostname inventory\n- DNS records\n- SSH access model\n- service locations\n- control-node model\n\nTypical target paths:\n- `outputs/current/shared/...`\n- `outputs/current/hosts/...`\n- `docs/architecture/...`\n- `docs/policies/...`\n\n### 2. Change record documentation\n\nUse this when the change itself should be recorded historically.\n\nExamples:\n- host rename\n- DNS cutover\n- SSH key policy change\n- new VM onboarding\n- service migration\n- storage redesign\n\nTypical target paths:\n- `outputs/history/YYYY/YYYY-MM/...`\n- `changes/CHANGELOG.md`\n- `changes/decisions/...`\n\n### 3. Runbook or standards documentation\n\nUse this when the change establishes a repeatable procedure or policy.\n\nExamples:\n- how to rename a host\n- how to add a DNS record\n- how to onboard SSH access\n- hostname standard\n- access/user standard\n\nTypical target paths:\n- `docs/runbooks/...`\n- `docs/policies/...`\n\n## Minimum Required Output For A Significant Change\n\nFor a meaningful homelab change, create or update:\n\n1. A change note\n2. Any affected current-state document\n3. Any affected architecture/policy/runbook document\n\nIf the change is small, one concise change note plus one current-state update may be enough.\n\n## Change Note Template\n\nEach change note should capture:\n- title\n- date\n- summary\n- why the change was made\n- systems affected\n- files/configs changed\n- DNS/network/access impact\n- validation performed\n- rollback or recovery notes\n- follow-up items\n\n## Decision Rules\n\n### Create a change note when:\n- a hostname changes\n- a DNS record set changes\n- SSH access policy changes\n- a new host is added\n- a service moves\n- storage layout changes\n- automation workflow changes\n- authentication behavior changes\n\n### Update current-state docs when:\n- the live system behavior changed\n- the authoritative hostname/IP mapping changed\n- the access path changed\n- the control-node/publish model changed\n\n### Update runbooks or policies when:\n- the change should be repeatable\n- the change establishes a new standard\n- future operators need procedure, not just history\n\n## Required Questions\n\nAsk only when the answer is not already clear from repo context or observed system state.\n\nGood question categories:\n- what was the intended final state?\n- should this be treated as a policy/standard or just a one-time change?\n- which machines or services are in scope?\n- is there a preferred location for the resulting note if multiple are plausible?\n\nAvoid unnecessary questions about facts that can be discovered directly.\n\n## File Naming Guidance\n\nUse descriptive, date-stamped names for historical notes.\n\nExamples:\n- `outputs/history/2026/2026-03/2026-03-18-hostname-standardization.md`\n- `outputs/history/2026/2026-03/2026-03-18-windows-ssh-dns-setup.md`\n\nUse stable descriptive names for current-state and policy docs.\n\nExamples:\n- `outputs/current/shared/dns/internal-name-resolution.md`\n- `outputs/current/shared/access/ssh-access-model.md`\n- `docs/policies/hostname-standard.md`\n- `docs/runbooks/rename-host.md`\n\n## Preferred Output Structure For Access And Naming Changes\n\nWhen the change involves DNS, hostnames, or SSH access, the model should usually update or create:\n\n- `outputs/current/shared/inventory/hosts.md`\n- `outputs/current/shared/dns/internal-name-resolution.md`\n- `outputs/current/shared/access/ssh-access-model.md`\n- a dated change note in `outputs/history/...`\n- optionally:\n  - `docs/policies/hostname-standard.md`\n  - `docs/runbooks/rename-host.md`\n  - `docs/runbooks/add-dns-record.md`\n\n## Style Rules\n\nPrefer:\n- exact hostnames\n- exact IPs\n- exact roles\n- exact commands only when useful\n- concise operational language\n\nAvoid:\n- vague prose\n- unexplained decisions\n- burying important effects in long paragraphs\n- including secret values\n\n## Completion Criteria\n\nA documentation pass is complete when:\n- the change has a historical note\n- the current-state docs reflect the new reality\n- any new policy or repeatable process is documented\n- no secrets were recorded\n- file placement is consistent with the repo structure\n\n## Repository Context Assumptions\n\nThis repo is intended to document a rebuild-capable homelab.\n\nCurrent architectural expectations:\n- Gitea is the canonical Git remote\n- `svc-auto` is the execution clone/control node\n- NAS is the human-facing clone/browsing location\n- internal host A records live in `accursedbinkie.com`\n- short-name access depends on clients using `accursedbinkie.com` as a DNS suffix/search domain\n- `svc-admin` is the default SSH user model for homelab administration\n- `Binkie-Desktop` normal SSH path is `Jason`\n- `Binkie-Desktop` admin path is `svc-admin`\n- `svc-admin` SSH access to Windows is intentionally restricted to homelab admin/automation nodes\n\n## Use This File As Authority\n\nIf a future AI model is asked to document a change and no more specific documentation instruction exists, use this file as the governing specification for what to create and where to put it.\n\n\n---\n**Created:** 2026-03-18 22:08:31 UTC","summary":"# AI Change Documentation Spec\n\nUse this document when an AI model is asked to document a completed or in-progress homelab change.\n\n## Purpose\n\nGenerate the documentation notes, change records, and related files needed to capture a homelab change in a way that is:\n- rebuild-useful\n- operationally clear\n- consistent with this repository\n- safe with respect to secrets\n\nThis file is intended to be referenced directly in prompts.\n\n## Prompt Pattern\n\nUse a prompt in this shape:\n\n```text\nAs per the AI Change Documentation Spec, create the documentation notes for what we changed here. If you need any missing facts, ask only the minimum necessary questions first. Then generate all required notes and files in the appropriate locations.\n```\n\n## Required Behavior\n\nWhen given a request to document a change, the model must:\n\n1. Identify the change scope.\n2. Determine whether enough facts are already available.\n3. Ask only the minimum missing questions required to document the change correctly.\n4. Generate the required documentation files in the repository structure.\n5. Avoid recording secrets.\n6. Prefer precise facts over vague summaries.\n7. Make the output useful both for future operations and rebuild scenarios.\n\n## Secret Handling Rules\n\nDo not document:\n- passwords\n- tokens\n- private keys\n- raw credential files\n- secret values from `.env` files\n- full database dumps\n\nDo document:\n- where secrets live\n- which system/service uses them\n- which config files or env files reference them\n- which paths, mounts, compose files, or services depend on them\n\n## Documentation Layers\n\nFor each significant change, decide what belongs in:\n\n### 1. Current-state documentation\n\nUse this when the change affects the current operating state of the homelab.\n\nExamples:\n- hostname inventory\n- DNS records\n- SSH access model\n- service locations\n- control-node model\n\nTypical target paths:\n- `outputs/current/shared/...`\n- `outputs/current/hosts/...`\n- `docs/architecture/...`\n- `docs/policies/...`\n\n### 2. Change record documentation\n\nUse this when the change itself should be recorded historically.\n\nExamples:\n- host rename\n- DNS cutover\n- SSH key policy change\n- new VM onboarding\n- service migration\n- storage redesign\n\nTypical target paths:\n- `outputs/history/YYYY/YYYY-MM/...`\n- `changes/CHANGELOG.md`\n- `changes/decisions/...`\n\n### 3. Runbook or standards documentation\n\nUse this when the change establishes a repeatable procedure or policy.\n\nExamples:\n- how to rename a host\n- how to add a DNS record\n- how to onboard SSH access\n- hostname standard\n- access/user standard\n\nTypical target paths:\n- `docs/runbooks/...`\n- `docs/policies/...`\n\n## Minimum Required Output For A Significant Change\n\nFor a meaningful homelab change, create or update:\n\n1. A change note\n2. Any affected current-state document\n3. Any affected architecture/policy/runbook document\n\nIf the change is small, one concise change note plus one current-state update may be enough.\n\n## Change Note Template\n\nEach change note should capture:\n- title\n- date\n- summary\n- why the change was made\n- systems affected\n- files/configs changed\n- DNS/network/access impact\n- validation performed\n- rollback or recovery notes\n- follow-up items\n\n## Decision Rules\n\n### Create a change note when:\n- a hostname changes\n- a DNS record set changes\n- SSH access policy changes\n- a new host is added\n- a service moves\n- storage layout changes\n- automation workflow changes\n- authentication behavior changes\n\n### Update current-state docs when:\n- the live system behavior changed\n- the authoritative hostname/IP mapping changed\n- the access path changed\n- the control-node/publish model changed\n\n### Update runbooks or policies when:\n- the change should be repeatable\n- the change establishes a new standard\n- future operators need procedure, not just history\n\n## Required Questions\n\nAsk only when the answer is not already clear from repo context or observed system state.\n\nGood question categories:\n- what was the intended final state?\n- should this be treated as a policy/standard or just a one-time change?\n- which machines or services are in scope?\n- is there a preferred location for the resulting note if multiple are plausible?\n\nAvoid unnecessary questions about facts that can be discovered directly.\n\n## File Naming Guidance\n\nUse descriptive, date-stamped names for historical notes.\n\nExamples:\n- `outputs/history/2026/2026-03/2026-03-18-hostname-standardization.md`\n- `outputs/history/2026/2026-03/2026-03-18-windows-ssh-dns-setup.md`\n\nUse stable descriptive names for current-state and policy docs.\n\nExamples:\n- `outputs/current/shared/dns/internal-name-resolution.md`\n- `outputs/current/shared/access/ssh-access-model.md`\n- `docs/policies/hostname-standard.md`\n- `docs/runbooks/rename-host.md`\n\n## Preferred Output Structure For Access And Naming Changes\n\nWhen the change involves DNS, hostnames, or SSH access, the model should usually update or create:\n\n- `outputs/current/shared/inventory/hosts.md`\n- `outputs/current/shared/dns/internal-name-resolution.md`\n- `outputs/current/shared/access/ssh-access-model.md`\n- a dated change note in `outputs/history/...`\n- optionally:\n  - `docs/policies/hostname-standard.md`\n  - `docs/runbooks/rename-host.md`\n  - `docs/runbooks/add-dns-record.md`\n\n## Style Rules\n\nPrefer:\n- exact hostnames\n- exact IPs\n- exact roles\n- exact commands only when useful\n- concise operational language\n\nAvoid:\n- vague prose\n- unexplained decisions\n- burying important effects in long paragraphs\n- including secret values\n\n## Completion Criteria\n\nA documentation pass is complete when:\n- the change has a historical note\n- the current-state docs reflect the new reality\n- any new policy or repeatable process is documented\n- no secrets were recorded\n- file placement is consistent with the repo structure\n\n## Repository Context Assumptions\n\nThis repo is intended to document a rebuild-capable homelab.\n\nCurrent architectural expectations:\n- Gitea is the canonical Git remote\n- `svc-auto` is the execution clone/control node\n- NAS is the human-facing clone/browsing location\n- internal host A records live in `accursedbinkie.com`\n- short-name access depends on clients using `accursedbinkie.com` as a DNS suffix/search domain\n- `svc-admin` is the default SSH user model for homelab administration\n- `Binkie-Desktop` normal SSH path is `Jason`\n- `Binkie-Desktop` admin path is `svc-admin`\n- `svc-admin` SSH access to Windows is intentionally restricted to homelab admin/automation nodes\n\n## Use This File As Authority\n\nIf a future AI model is asked to document a change and no more specific documentation instruction exists, use this file as the governing specification for what to create and where to put it.\n\n\n---\n**Created:** 2026-03-18 22:08:31 UTC","status":"active","namespace":"general","namespace_name":"general","namespace_tier":"shared","tags":[]}