dotHuman
Protocol Handbook v0.3

dotHumanize

Depth

The seed pseudoskill that ships with dotHuman. Drop it into any project, ask it to understand the repo, and it builds you a .human/ you can trust. To run it is to put a dotHuman on it — see the Quickstart.

dotHumanize is the seed pseudoskill that ships with the protocol — the thing you run to put a dotHuman on a project. It's a verb because it works whatever state the folder is in: it sets up a .human/ the first time — whether the folder is empty or an established codebase — and updates it on every run after. It installs itself into the .human/ it creates, so it's there next time.

The problem it solves

Point an AI at an unfamiliar codebase and say "understand this," and you usually get a confident summary that is partly invented — and the invented parts look exactly as confident as the real ones. So you end up proofreading facts you can't see.

dotHumanize flips that. It states only what it can prove, marks every guess as a guess, and is built around one rule — don't fabricate the "why"; it leaves a blank for you instead. You spend your attention adding judgment, not correcting facts.

Four kinds of knowledge

Everything it writes falls into one of four buckets, each handled differently:

Kind Examples How it's written
Verifiable languages, dependencies, run/build/test commands, layout Asserted, with its source — and pulled from the files, not from memory.
Documented what the README/docs claim Surfaced but marked unverified — quoted, never promoted to fact until you confirm it.
Inferable what a folder is for, likely gotchas, domain terms Written, but flagged [review] — never stated as fact.
Unknowable the why, the intent, war-story gotchas Left as a blank for you to fill. Empty is honest; a confident wrong "why" is what destroys trust.

The one rule it's built around: don't fake the why. A blank you fill is a win; a plausible-but-wrong answer you have to catch and delete is the failure the protocol exists to prevent.

What it produces

A scaffolded five-pillar .human/: Comprehension (a context-reset briefing, architecture, gotchas, glossary), a captain's log whose Open Items are your review checklist, two Goals (the scaffolding, done — and a review goal, yours), Evergreen runbooks, and an empty Reports pillar. Every generated file leads with a version note and a one-line summary.

How to use it

The five-minute path is the Quickstart: drop it in, say "dotHumanize this repo," let it scaffold, then do the human-in-the-loop review. The review is resumable anytime — trust is graduated: the more you confirm, the more trustworthy your .human/, and every future goal builds on it.

How it works — two halves

dotHumanize is deliberately split, and that split is what makes it trustworthy:

  1. A script does the facts. A deterministic extractor walks the project, reads the real files, and emits a list of facts — each tagged with where it came from. Same project in → the same facts out, every time, on any OS. A fact that isn't there is reported as "not found," never guessed.
  2. The agent fills fixed templates on a short leash. Its only moves are to drop a fact into its slot (with the source) or to write a guess into a clearly-marked [review] block. It may not reword facts, invent structure, or write the why.

The facts can't drift, and the guesses can't masquerade as facts. This is the protocol's most deterministic, tightly-bounded piece on purpose — it's the foundation everything else stands on.

It adapts to what it finds

  • Any stack — JavaScript/TypeScript, Python, PHP (incl. Laravel and WordPress), Go, Rust, Ruby, Terraform, static sites — and it lists every declared dependency, so coverage never depends on a hand-kept list.
  • Non-code directories — a content or design folder has no manifests, but a real method lives in its file types, folder structure, and naming conventions; dotHumanize reads those too.
  • A brand-new empty repo — nothing to scan, so it interviews you and lays the floor from your intent.
  • A root of many projects — it surveys each subproject and tells you what's there. You choose the depth: a quick survey, the standard pass, or a deep per-project dive.
  • A re-run — it refreshes the facts and shows you only what changed; it never overwrites the judgment you supplied.

Why you can trust it

  • Deterministic & bounded — same input, identical output; a defined surface in, a defined shape out.
  • Auditable — every line traces to a file (a fact) or a [review] flag (a guess). Nothing is unattributable.
  • Secret-safe by design — it's built to read environment variable names, not their values, to keep secrets out of the output.
  • Tested — it ships with a gate harness that runs it against a fixture project per shape and asserts the behavior, so changes can't quietly regress it.

First run, and every run after

dotHumanize is built to run more than once:

  • The first run sets up the floor. On an empty folder it interviews you and lays the pillars from your intent; on an existing project it reads what's actually there and lays a floor that reflects it. Either way you get a five-pillar .human/ that states only what it can prove.
  • Every run after updates it. It re-reads the project, shows you only what's changed since last time, and flags anything that's gone stale — never overwriting the judgment you supplied.

Unlike the pseudoskills you grow over time from accumulated Lessons, dotHumanize ships ready-made (as does dotCoach, the practice coach it offers you at review-close) — it has to, since its whole job is to create the floor those others grow in.

The other half of the work is yours. The protocol is built so the human in the loop owns the floor — supplying the why the code can't, confirming or striking inferences, deciding what graduates — and spending attention on judgment, never on re-typing facts. Running dotHumanize is the moment a project goes from "code an AI re-figures-out every session" to one with a living, human-verified floor.

Related

Try it

Last updated