kristovatlas

Documentation writing style guide

Notes for writing engineering documentation: reference pages, how-to guides, tutorials, READMEs, runbooks, release notes, design docs, and blog posts. The goal is prose that reads like a competent engineer wrote it. Obvious AI-generated text costs credibility with a technical audience and reads as low effort regardless of the quality of the underlying work. Documentation adds a second requirement on top of that: it must stay unambiguous for a reader who is in a hurry, under stress, or reading in a second language. Section 7 adopts ASD-STE100 (Simplified Technical English) for that reason.

0. The goal is a human voice with controlled clarity

Read this first. Everything below is a set of heuristics toward clear prose a person would write. Do not treat it as a checklist to satisfy mechanically.

• Over-correction is its own tell. Prose that dodges every banned word but comes out clipped, choppy, and stripped of personality lands in a different uncanny valley. Keep th

kristovatlas

A deterministic gate for AI code review

LLMs are non-deterministic and their context gets polluted over a long session. The orchestration around them should not inherit those properties. Anywhere a step in your workflow can be made exact and machine-checked, make it exact, so the fuzzy part is contained to the model's actual output and can't quietly skip or corrupt the process around it.

PR review is a good place to apply this. An agent running review passes can skip one, forget one of several, or merge over a finding it decided wasn't worth fixing, and a chat-based "all reviews passed" gives you no way to know. This is how to close that gap.

The rule

Every PR commits the review results as files a CI check reads. The merge is blocked unless the results are present, complete, current, and clear of unresolved serious findings. The reviews stay probabilistic. Whether they happened and cleared the bar becomes a yes/no that CI answers, and an agent cannot talk its way past a required status check the way

kristovatlas

Blog writing style guide

Notes for engineering blog writing. The goal: read like a human engineer wrote it, not like it came out of a chatbot. Two big reasons. It's more credible with a technical audience, and obvious AI-generated prose reads as low-effort regardless of how good the underlying work is.

0. The goal is a human voice, not a word filter

Read this first. Everything below is a heuristic toward prose a person would write, not a checklist to satisfy mechanically.

• Over-correction is its own tell. Prose that dodges every banned word but comes out clipped, choppy, and stripped of personality lands in a different uncanny valley. Keep the occasional analogy, aside, and bit of structure that a real writer would use.
• Don't swap one crutch for another. If every em-dash becomes a parenthesis, parentheses are the new tell. If banned words get replaced by near-synonyms, nothing changed.

kristovatlas

#!/usr/bin/env bash
set -euo pipefail

# ── Helpers ──────────────────────────────────────────────────────
info()  { printf '\033[1;34m[INFO]\033[0m  %s\n' "$*"; }
ok()    { printf '\033[1;32m[OK]\033[0m    %s\n' "$*"; }
err()   { printf '\033[1;31m[ERROR]\033[0m %s\n' "$*" >&2; }

# ── Pre-flight: require npm ──────────────────────────────────────
if ! command -v npm &>/dev/null; then

kristovatlas

import sys


def is_separator(line):
    """Check if a line is a horizontal separator (e.g. ├───┼───┤, ╞═══╪═══╡, etc.)"""
    stripped = line.strip()
    # Separator lines are made up of box-drawing border characters and have no letter/digit content
    border_chars = set('─━═┼╪╫┬┴├┤┌┐└┘╔╗╚╝╠╣╦╩╬╞╡╥╨╤╧╟╢+|-=')
    return bool(stripped) and all(c in border_chars or c.isspace() for c in stripped)

kristovatlas

import sys

def main():
    if len(sys.argv) != 2:
        print("Usage: python fix_railway_logs.py <log_file>")
        sys.exit(1)

    filename = sys.argv[1]
    prefix_length = 38
    content_parts = []

kristovatlas

import ast
import json
import sys

def parse_nested_json(obj):
    """Recursively parse any string values that are valid JSON into objects."""
    if isinstance(obj, dict):
        return {k: parse_nested_json(v) for k, v in obj.items()}
    elif isinstance(obj, list):
        return [parse_nested_json(i) for i in obj]

kristovatlas

"""
https://twitter.com/elliot_olds/status/1319364546880942080

To keep calculations simple, let's fix population size to 100
"""
POPULATION = 100
FRED_PROB_FIRST = 1/(0.6 * POPULATION)
NOT_FRED_PROB_FIRST = 1-FRED_PROB_FIRST

def prob_no_blood_type(population, num_crime_scene):

kristovatlas

#python3
# Usage: emailer.send(recipient_email, mail_subject, message)
#https://stackabuse.com/how-to-send-emails-with-gmail-using-python/
import smtplib

gmail_user = 'username@gmail.com'
gmail_password = 'password_goes_here'
sent_from = gmail_user

def send(recipients, subject, body):

kristovatlas

NUM_FIB_NUMS = 100

F1 = 0
F2 = 1
POS = 2

print "0,0"
print "1,1"

for count in range(1, NUM_FIB_NUMS + 1):