The HERR Method

Heuristic Evaluation → Remedy → Reflection. HERR is a reusable operating discipline for AI-assisted software development. It keeps an agent evidence-driven, scoped and verification-led while normal engineering controls continue to decide whether a change is safe to merge or release.

This repository maintains the method. Project_Instructions/ is the bundle copied into a new development project. The method repository's own goal, scorecard and evolution history are worked instances and must not be copied as project state.

Adopt it in a new project

1. Copy Project_Instructions/ into the project root.

2. Create the project's live HERR files from the supplied templates:

   • 08_HERR_GOAL_TEMPLATE.md → HERR_GOAL.md
   • 09_HERR_IMPROVING_LOOP_INSTANCE_TEMPLATE.md → HERR_IMPROVING_LOOP.md
   • 07_HERR_LIVING_SCORECARD_TEMPLATE.md → LIVING_SCORECARD.md
   • 05_HERR_PLAYBOOK.md → HERR_PLAYBOOK.md

3. Fill every required placeholder in all three of HERR_GOAL.md, HERR_IMPROVING_LOOP.md and LIVING_SCORECARD.md, and delete the "copy this file" note at the top of each. Name the objective, the stable TERM-*, GATE-*, TRIP-*, GAP-* and APP-* IDs, score thresholds, project gates, hard stops and evidence sources.

4. Create the ledger and its directories:

   python Project_Instructions/herr.py init-ledger
   

   The command writes HERR_Cycles/cycle-ledger.jsonl with a unique ledger and event ID and creates HERR_Cycles/cycles/ and HERR_Cycles/runs/. Never copy 12_HERR_CYCLE_LEDGER_TEMPLATE.jsonl into the project. That file is the shape reference for the meta row; its LEDGER-TEMPLATE identity is rejected as live state, so copying it produces a failing adoption.

5. Connect the agent to 01_HERR_AI_DEVELOPMENT_INSTRUCTIONS.md. If the host supports project skills, install skills/herr-cycles/SKILL.md in that host's project skill directory. Keep the adapter static: gates and thresholds belong only in HERR_IMPROVING_LOOP.md.

6. Verify the adoption before the first run:

   python Project_Instructions/herr.py validate
   python Project_Instructions/verify_herr_adoption.py
   

   Both must pass. Treat a reported error as a configuration gap to close, never as a value to invent.

7. In the adopting project, invoke:

run eval 30 cycles, show scorecard

Maintaining this repository rather than adopting from it? Run python scripts/verify_project_instruction_bundle.py here before publishing a bundle release. It checks the copied bundle's own integrity and is not part of an adopting project's setup.

The requested count is a maximum, not a work quota. The run stops earlier when the goal is met, evidence is exhausted, a gate fails, the project degrades or a human decision is required. A valid run can therefore complete after zero to thirty cycles. This is intentional: forcing thirty remedies after the honest gaps run out rewards invented work.

Read Project_Instructions/README.md for the complete adoption and operating procedure.

What the copied bundle contains

Project_Instructions/HERR_BUNDLE.json is the authoritative manifest; this table describes what each entry is for. A repository check fails when the two disagree.

File	Role
README.md	Adoption and operating procedure for the bundle
HERR_BUNDLE.json	Machine-readable release manifest and compatibility declaration
00_HERR_IMPROVING_LOOP.md	Multi-cycle protocol, including “run eval 30 cycles”
01_HERR_AI_DEVELOPMENT_INSTRUCTIONS.md	Standing agent instructions
02_HERR_ENGINEERING_CONTROLS.md	Version control, test, review, security and release controls
03_HERR_TASK_BRIEF_TEMPLATE.md	Task brief patterns
04_HERR_SCORECARD_AND_QUALITY_GATES.md	Heuristics, evidence rules and quality gates
05_HERR_PLAYBOOK.md	Clean starter template for project-specific lessons
06_HERR_CHANGE_REPORT_TEMPLATE.md	Final report and review template
07–09	Live-state templates: scorecard, goal and loop instance
10–11	Per-cycle and per-run evidence templates
12_HERR_CYCLE_LEDGER_TEMPLATE.jsonl	Ledger meta-row shape reference; never copied into a project
13_HERR_LEDGER_SCHEMA.json	Declarative schema-2 event shapes
14_HERR_CHANGE_TYPE_REGISTRY.json	Versioned cross-layer change-type registry
15_HERR_DATA_HANDLING.md	Evidence classification, minimization and retention
16_HERR_HOST_ADAPTERS.md	Codex, Claude Code and generic host installation
AGENTS.md.template, CLAUDE.md.template	Concise primary-instruction adapters
skills/herr-cycles/SKILL.md	Optional trigger adapter for skill-capable agents
herr.py	Atomic run and cycle lifecycle, recovery and ledger validation
verify_herr_adoption.py	Target-project adoption check
CHANGELOG.md, UPGRADING.md	Release history and live-state migration guide
LICENSE	MIT license; retain the notice when copying

Method repository versus project instance

The repository that maintains the method also runs the method on itself. Its own goal, scorecard, playbook, host adapter and evolution history are worked instances that govern the maintaining repository alone. They are not defaults for a new software product, and a published copy of the bundle does not carry them. This separation prevents a copied project from inheriting the method repository's scores, backlog, paths or historical conclusions.

The long-form method sources and rendered artifacts remain in the repository for reference. The copy boundary is deliberately just Project_Instructions/.

Non-negotiable eval rules

• Register a cycle's target, lever, prediction and falsifier before the first remedy edit.
• Measure the registered falsifier; passing tests alone does not prove improvement.
• Retain no-change, worsened, unmeasurable and blocked results in the append-only ledger.
• Treat the composite as a trend indicator, never as a substitute for per-heuristic gates.
• Never invent a baseline. Unmeasured means unscored, not zero.
• Update project state only from evidence produced or inspected in the current cycle.

---

Loud Division AB · Nils-Bertil Carlson Estrada