From 2f696ef4708113082603b97180e3a8baae093656 Mon Sep 17 00:00:00 2001
From: Jan De Landtsheer <jan@delandtsheer.eu>
Date: Mon, 29 Sep 2025 11:58:48 +0200
Subject: [PATCH] docs: add KILO_HOWTO.md process guide for Kilo context reload
 and docs hygiene

---
 KILO_HOWTO.md | 129 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 129 insertions(+)
 create mode 100644 KILO_HOWTO.md

diff --git a/KILO_HOWTO.md b/KILO_HOWTO.md
new file mode 100644
index 0000000..dfe75d6
--- /dev/null
+++ b/KILO_HOWTO.md
@@ -0,0 +1,129 @@
+# KILO_HOWTO: Continuity and documentation hygiene
+
+Purpose
+- Explain how Kilo regains context after restart and how to keep docs in sync with code.
+- Keep this file short, actionable, and authoritative for process.
+
+What Kilo preloads by default after a restart
+- [PROMPT.md](PROMPT.md)
+- [README.md](README.md)
+- [TODO.md](TODO.md)
+- [docs/adr/README.md](docs/adr/README.md)
+Notes
+- Kilo can preload the entire docs/ tree on request. Ask “preload docs” or link to a specific file.
+- Anything committed in-repo is considered the source of truth.
+
+Update triggers by document
+- [PROMPT.md](PROMPT.md): Update when scope/constraints change.
+- [README.md](README.md): Update when CLI flags, defaults, or preview/apply behavior change.
+- [TODO.md](TODO.md): Update when starting/finishing tasks (end-of-day hygiene).
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md): Update when component boundaries or contracts change.
+- [docs/adr/README.md](docs/adr/README.md) + ADR files: Add when decisions are made or reversed.
+- [docs/DEV_WORKFLOW.md](docs/DEV_WORKFLOW.md): Update when build/test/run steps change.
+- [docs/API-SKELETONS.md](docs/API-SKELETONS.md): Update when public surfaces or CLI/programmatic APIs change.
+
+Lightweight process guardrails
+- Every feature/change should update the relevant docs in the same commit/PR.
+- Prefer ADRs for decisions that affect architecture, data formats, or safety policies.
+- Keep this KILO_HOWTO.md updated if the maintenance process itself changes.
+
+Pull request checklist (copy into your template)
+
+- [ ] Updated [README.md](README.md) for any CLI or behavior change
+- [ ] Added/updated ADR in [docs/adr/](docs/adr/README.md) if design changed
+- [ ] Adjusted [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) if component boundaries changed
+- [ ] Synced [TODO.md](TODO.md) (completed/in-progress/next)
+- [ ] docs sanity check passes ([tools/docs_check.sh](tools/docs_check.sh))
+- [ ] Unit/integration tests updated or added
+
+Minimal docs sanity checks
+Create [tools/docs_check.sh](tools/docs_check.sh) and mark it executable. Run it locally and in CI.
+
+Example tools/docs_check.sh
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "[docs_check] verifying referenced files exist"
+paths=(
+  "PROMPT.md"
+  "README.md"
+  "TODO.md"
+  "docs/adr/README.md"
+  "docs/ARCHITECTURE.md"
+)
+for p in "${paths[@]}"; do
+  [[ -f "$p" ]] || { echo "missing: $p" >&2; exit 1; }
+done
+
+echo "[docs_check] verifying CLI flags documented"
+help_out="$(cargo run -- --help 2>/dev/null || true)"
+if [[ -n "$help_out" ]]; then
+  # Require README to mention each long flag token like --apply or --show
+  flags=$(grep -oE -- '--[a-z0-9-]+' <<<"$help_out" | sort -u)
+  missing=0
+  while read -r f; do
+    grep -q -- "$f" README.md || { echo "README missing flag: $f" >&2; missing=1; }
+  done <<<"$flags"
+  [[ $missing -eq 0 ]] || exit 1
+else
+  echo "[docs_check] skipped CLI verification (binary not runnable in this context)"
+fi
+
+echo "[docs_check] verifying ADR index lists all ADRs"
+if [[ -d docs/adr ]]; then
+  want=$(find docs/adr -maxdepth 1 -type f -name 'ADR-*.md' -printf '%f\n' | sort -u)
+  if [[ -n "$want" ]]; then
+    idx="docs/adr/README.md"
+    for f in $want; do
+      grep -q -- "$f" "$idx" || { echo "ADR not indexed in $idx: $f" >&2; exit 1; }
+    done
+  fi
+fi
+
+echo "[docs_check] OK"
+```
+
+CI wiring (GitHub Actions example)
+Create [.github/workflows/ci.yml](.github/workflows/ci.yml) with a docs job that runs tools/docs_check.sh.
+
+Example .github/workflows/ci.yml snippet
+
+```yaml
+name: CI
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+jobs:
+  build-and-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+          override: true
+      - name: Build
+        run: cargo build --locked
+      - name: Test
+        run: cargo test --locked
+      - name: Docs sanity
+        run: bash tools/docs_check.sh
+```
+
+Daily habits
+- At the end of a work session, update [TODO.md](TODO.md) to reflect reality (completed/in-progress/next).
+- When introducing or reversing a design decision, add an ADR and index it in [docs/adr/README.md](docs/adr/README.md).
+- When changing CLI or behavior, update [README.md](README.md) in the same commit as the code change.
+
+Asking Kilo to (re)load context
+- “preload docs” to read the entire docs/ tree.
+- Link specific files in your message; Kilo will read those first.
+
+Rationale
+- Keeping docs changes co-located with code in the same commit prevents drift.
+- A single fast docs_check.sh closes the gap when someone forgets an update.
+- Small, well-defined authorities ([PROMPT.md](PROMPT.md), [README.md](README.md), [TODO.md](TODO.md), ADRs) reduce duplication.
\ No newline at end of file