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:
parent
a99ac4388b
commit
ac17e6e4ab
1 changed files with 43 additions and 0 deletions
43
CLAUDE.md
43
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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue