From 07777212ec184eb88093f62148cae3fec6038a82 Mon Sep 17 00:00:00 2001
From: Erich Blume <blume.erich@gmail.com>
Date: Tue, 3 Feb 2026 21:16:50 -0800
Subject: [PATCH] Add deployment verification prompts to doc-random

- Add "Verify Deployed State" section to review checklist
- Expand how-to with commands for ArgoCD, Ansible, and Pulumi verification

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 .../knowledgebase/review-documentation.md     | 39 +++++++++++++++++++
 mise-tasks/doc-random                         |  6 ++-
 2 files changed, 44 insertions(+), 1 deletion(-)

diff --git a/docs/how-to/knowledgebase/review-documentation.md b/docs/how-to/knowledgebase/review-documentation.md
index 769fc3e..e286e1b 100644
--- a/docs/how-to/knowledgebase/review-documentation.md
+++ b/docs/how-to/knowledgebase/review-documentation.md
@@ -33,6 +33,45 @@ When reviewing a documentation card, consider:
 | **Frontmatter** | Are title and tags appropriate? |
 | **Related** | Should it link to related cards? |
 
+## Verify Deployed State
+
+For service reference cards, verify the documentation matches reality:
+
+### ArgoCD Apps (Kubernetes services)
+
+Check if the app is synced and healthy:
+
+```bash
+argocd app get <app-name>
+argocd app diff <app-name>  # Show pending changes
+```
+
+If out of sync, either the docs are stale or a deployment is pending.
+
+### Ansible Roles (indri services)
+
+Check if the role applies idempotently (no changes needed):
+
+```bash
+mise run provision-indri -- --tags <role> --check --diff
+```
+
+If changes would be made, either the docs are stale or the host has drifted.
+
+### Pulumi (Tailscale ACLs, DNS)
+
+Check for drift:
+
+```bash
+# Tailscale ACLs
+cd pulumi/tailscale && pulumi preview
+
+# DNS (Gandi)
+cd pulumi/gandi && pulumi preview
+```
+
+If changes are pending, investigate whether docs or infrastructure is stale.
+
 ## When to Review
 
 Consider running `mise run doc-random` during:
diff --git a/mise-tasks/doc-random b/mise-tasks/doc-random
index 01a584d..05cad28 100755
--- a/mise-tasks/doc-random
+++ b/mise-tasks/doc-random
@@ -72,7 +72,11 @@ def main() -> int:
         "• Is the card too large and should be split?\n"
         "• Is the card too small and should be merged?\n"
         "• Does the frontmatter (tags, title) make sense?\n"
-        "• Is the card in the correct category (reference/how-to/etc)?",
+        "• Is the card in the correct category (reference/how-to/etc)?\n\n"
+        "[bold]Verify Deployed State:[/bold]\n\n"
+        "• If ArgoCD app: is it synced? (argocd app get <app>)\n"
+        "• If Ansible role: does it apply idempotently? (--check --diff)\n"
+        "• If Pulumi: is there drift? (pulumi preview)",
         title="[bold yellow]Review Guidance[/bold yellow]",
         border_style="yellow",
     ))