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