# 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.