docs(claude): add five-step algorithm — apply in order

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.
This commit is contained in:
russell@unturf.com 2026-05-01 14:07:07 -04:00
parent a99ac4388b
commit ac17e6e4ab
No known key found for this signature in database

View file

@ -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