Files

T

igodwin cb0c5b4614 Move runbooks into domain directories

od-db-backup.md becomes od/db-backup.md -- the hyphen becomes a slash, so
the fetch command is exactly as long to type as before. That mattered: the
length of a hand-typed command is the constraint this repo is organized
around, and a reorganization that lengthened it would have been a net loss.

Scripts deliberately stay flat in scripts/ with their domain prefix.
Everything executable in one directory is the set worth reading before it
runs, and nesting five files by domain would add characters without adding
clarity.

Updates every reference: README Contents (now grouped by directory), the
layout section, both fetch examples, inter-runbook links, and the .NOTES
headers in all five scripts. Verified every markdown link resolves on disk
and that Contents and the filesystem agree in both directions.

Records the naming rule in CONTRIBUTING so the next file lands correctly.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HwcG1jLs1T425QRMxtjxP7

2026-09-02 23:15:48 -07:00

3.5 KiB

Raw Permalink Blame History

Contributing (note-to-self)

Solo-maintained. This file exists to keep future-me honest.

The rule

Procedures only. No particulars.

This repo is public-read. Anything that identifies a client or would let a reader act against a client environment goes to the private tier — no exceptions.

Never commit:

Client / business names, site identifiers
Hostnames, IPs, subnets, SSIDs, MAC addresses
Usernames, account names, email addresses
Passwords, keys, tokens, connection strings, license keys
Screenshots, exports, logs, or config dumps containing any of the above

Instead use placeholders: <CLIENT>, <SERVER>, <SHARE>, <SHARE_USER>, <USER>, <PASSWORD>. Filled-in versions live in the private tier (private repo or Bitwarden secure note).

Where things go

Content	Home
Generic procedure with placeholders	This repo
Anything needing a credential	Private tier
Client-specific config / values	Private tier
Any identifying detail	Private tier

If a step can't be written without a real particular, it doesn't belong here — split the particular out to the private tier and reference it as a placeholder.

Naming

Runbooks go in a domain directory and drop the prefix — od/db-backup.md, not od-db-backup.md. The directory is the prefix, which keeps the fetch command exactly as short as it was. Existing domains are od/ and sec/; add win/, m365/, or net/ when the first file needs one.

Scripts stay flat in scripts/ and keep their domain prefix. Everything executable lives in one directory on purpose — that is the set worth reading before it runs. Non-interactive scripts (Intune remediations) get their own sibling directory, not scripts/.

Filenames stay short: they are typed by hand on a client keyboard, often mid-incident. That constraint outranks descriptiveness.

Before every commit

Re-read the diff. Would a stranger learn who the client is, or how to reach their systems? If yes, stop.
No real hostnames/IPs/users/passwords — placeholders only.
No screenshots or pasted output with real data.
Scripts prompt for client-specifics at run time; they don't hard-code them.

Scripts

Scripts live under scripts/. Follow scripts/_template.ps1:

Prompt for placeholders with Read-Host — no editing before running, no param() (can't pass args through irm | iex).
Safe to run via irm <url> | iex from our own server.
Confirm before anything destructive or that reboots.
Check for admin explicitly (#Requires is not enforced under iex).

The as-is notice

Every runbook and script carries a short as-is notice — two lines under the # title in a .md, or at the end of the .NOTES block in a .ps1. Copy it when you add a file.

It is per-file rather than README-only for one reason: these are fetched by raw URL, so a reader who lands on a single runbook never sees the README or the LICENSE. The repo's context does not travel with the file.

Keep it to those two lines. It sits above genuinely important, procedure-specific warnings — never a live chart, stop the service before copying, confirm authorization before acting — and a longer legal preamble would train people to skip the top of the file, which is exactly where those warnings live.

Aim it at a stranger who found the repo, not at the quality of the procedure. These runbooks double as documented-procedure evidence; wording that implies the content is unreliable works against that.

3.5 KiB Raw Permalink Blame History