From ac17e6e4ab4cf10fe475bd5a3469dd12223f04d0 Mon Sep 17 00:00:00 2001 From: "russell@unturf.com" Date: Fri, 1 May 2026 14:07:07 -0400 Subject: [PATCH] =?UTF-8?q?docs(claude):=20add=20five-step=20algorithm=20?= =?UTF-8?q?=E2=80=94=20apply=20in=20order?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Engineering discipline added between operational rules and the orientation protocol. Walk the steps in sequence; skipping makes the next ones expensive. 1. Make the requirements less dumb (every requirement gets a name, not a department). 2. Delete the part or the process (10%+ put-back rate or you aren't deleting hard enough). 3. Simplify and optimize (only after 1 + 2). 4. Accelerate cycle time (only after simplifying — don't dig the grave faster). 5. Automate (last, not first). Connected to existing aborist conventions: - Step 1 traces every policy knob / schema invariant / verifier check to a specific defect or owner. Aligns with the "feedback memory" pattern (record the WHY). - Step 2 reinforces verifier-stays-binary and "no soft signals in the hard chain" — both are deletion-first rules. - Step 5 is why bench harnesses, distill runners, and ingest CLIs earned automation only after their underlying ops were simplified to single-purpose stages. --- CLAUDE.md | 43 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 93bbec4..c8c4239 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -249,6 +249,49 @@ during the JSON-mode hardening journey: - Prefer "defect" over "bug." - Check robots.txt before any web fetch the user didn't authorize. +## Five-step algorithm (apply in order) + +When proposing or evaluating change, walk these in sequence. Skipping a +step makes the next ones expensive and the system worse. + +1. **Make the requirements less dumb.** Challenge every requirement and + assumption — *especially* the ones from "smart" sources. Every + requirement should come with a person's name, not a department or + a generic appeal to "best practices." For aborist that means: every + policy knob, schema invariant, prompt rule, and verifier check + should trace to a specific failure or owner. If you can't name who + asked for it or which defect it closed, the requirement is suspect. + +2. **Delete the part or the process.** Actively remove unnecessary + steps, fields, components, or rules. If you aren't putting back at + least 10% of what you delete, you aren't deleting hard enough. For + aborist that means: prefer pruning prompt rules / policy fields / + rerank stages / cache columns over piling new ones on. The + verifier-stays-binary discipline and the "no soft signals in the + hard chain" rules are deletion-first guardrails. + +3. **Simplify and optimize.** Refine what remains — *only after* + steps 1 and 2. A common mistake is optimizing a process that + shouldn't exist. Don't add a faster index, a better tokenizer, or + a tighter loop until the surrounding stage has survived steps 1+2. + +4. **Accelerate cycle time.** Speed up the process — *only after* + simplifying. "If you're digging your grave, don't dig it faster." + For aborist: latency wins on a poorly-shaped retrieval pipeline + are graveyard-digging. + +5. **Automate.** Automate last, not first. Automating too early + produces inefficient, high-cost systems that nobody understands. + For aborist that means: hand-rolled before scripted, scripted + before declarative, declarative before generated. The bench + harness, distill runner, and ingest CLI all earned their + automation only after the underlying ops had been simplified + into single-purpose stages. + +Apply to tickets, prompt edits, retrieval-pipeline additions, schema +changes, and our own behavior. When in doubt, ask "have we tried +deleting it?" before reaching for steps 3-5. + ## Orientation protocol ```bash