# best-practices

Cross-project best practices extracted from real project work via the `/distill-best-practices` skill.

## How It Works

The knowledge distillation pipeline in `claude-foundations` processes session logs and memory files from all tracked projects, extracting generalisable practices into topic files here.

### Pipeline

1. **`/log`** — Captures session decisions and gotchas into per-project `memory/log/`
2. **`/reflect-logs`** — Processes logs into structured topic memory files
3. **`/distill-best-practices`** — Reads memory files across projects, proposes updates to this repo

### For Humans

Browse `BESTPRACTICES.md` for the full index. Each topic file is self-contained.

### For Agents

Container agents get this repo cloned to `/best-practices`. Read `BESTPRACTICES.md` for the index, then read only the topic files relevant to your task.

## Topics

| File | Description |
|------|-------------|
| `ansible.md` | Inventory, templates, idempotency, credential safety |
| `database-selection.md` | SQLite vs PostgreSQL decision criteria |
| `debugging.md` | Systematic diagnosis, full-chain testing, common pitfalls |
| `docker.md` | gosu PID 1, GIT_SSH_COMMAND scope, slim image patterns |
| `docker-uid-matching.md` | UID wrapper entrypoint, gosu pattern |
| `documentation.md` | CLAUDE.md, MEMORY.md, FUTURE.md, README.md structure |
| `git-source-control.md` | Commit practices, GitOps workflows, remote conventions |
| `helm.md` | Schema validation, version verification, values structure |
| `kubernetes.md` | Volume mounts, deployment strategies, naming, bootstrap ordering |
| `linting.md` | Tool choices per language, PostToolUse hook, pre-commit |
| `milestones.md` | Milestone workflow, verification, reflection process |
| `networking.md` | nftables, systemd sockets, Docker forwarding, TLS |
| `octopus-process-templates.md` | OCL syntax, step templates, Platform Hub patterns |
| `scripting.md` | Shell conventions, verification scripts, idempotency |
| `secrets-management.md` | SOPS + age, credential handling, encryption gotchas |
| `security-architecture.md` | Server boundary rule, proxy patterns, defense in depth |
| `skills-development.md` | Skill authoring, context injection, tool restrictions |
| `spec-driven-development.md` | Spec structure, requirement numbering, test-first workflow |
| `test-driven-development.md` | Edge case discovery, property-based testing, AI agent patterns |
| `validation.md` | Validate locally, deploy once; full-chain testing |

## Source Control

- **Gitea:** `skynet/best-practices`
- **Remote:** `git@gitea.oreillyit.nz-ai-enablement:skynet/best-practices.git`