Version: 2.3.4 Date: 2026-08-27 Status: Reusable process guide
This document defines a reusable process for AI-assisted software development. It is intended to make AI work more reliable, traceable and autonomous by forcing every development cycle through explicit evaluation, diagnosis, remedy, verification and reflection.
The process is called the Heuristic Evaluation-Remedy-Reflection Loop, abbreviated as the HERR Loop.
The goal is not to make an AI assistant generate more output. The goal is to make it produce better software changes with less hallucination, less drift and clearer evidence.
This process can be reused for:
- New feature development.
- Bug fixing.
- Architecture improvement.
- Documentation and specification refinement.
- Test coverage improvement.
- Refactoring.
- Security hardening.
- AI-assisted code review.
- Build-readiness and release-readiness checks.
The HERR Loop combines four ideas:
- Heuristic evaluation: inspect the current state against explicit quality dimensions.
- Remedy: apply targeted fixes for diagnosed gaps.
- Reflection: understand why the gaps existed and what pattern caused them.
- Playbook evolution: turn repeated lessons into reusable rules for future work.
The loop is:
Goal definition
-> Heuristic evaluation
-> Gap diagnosis
-> Remedy planning
-> Implementation
-> Verification
-> Reflection
-> Playbook update
-> Re-evaluation
The HERR Loop is not a replacement for normal engineering discipline. It should sit on top of:
- Version control.
- Automated tests.
- Code review.
- Continuous integration.
- Architecture decision records.
- Security review.
- Release management.
- Operational monitoring.
The HERR Loop is best understood as the AI operating discipline inside the software development process. It tells the AI how to reason, act, verify and learn.
-
The repository is the source of truth. The AI must inspect the actual code, tests and documents before making implementation claims.
-
Facts and assumptions must be separated. A fact is observed in code, tests, logs, documentation or user requirements. Anything else is an assumption.
-
Every change must serve the stated goal. The AI must avoid opportunistic rewrites, unrelated cleanup and speculative expansion.
-
Small verified remedies are preferred. The AI should make the smallest change that fully addresses the diagnosed gap.
-
A remedy is incomplete until verified. Verification may be automated tests, static checks, runtime checks, screenshots, manual inspection or explicit residual-risk reasoning.
-
Reflection must improve the next cycle. Reflection is not a summary. It identifies the pattern that caused the gap and converts it into a playbook rule when useful.
-
Drift is treated as a defect. If code, tests, schema, API, UI and documentation disagree, that disagreement is a quality problem.
-
No hallucinated architecture. The AI must not invent APIs, files, schemas, packages, test results, system behaviours or business rules.
Before starting a development cycle, define the following as clearly as possible.
| Input | Meaning |
|---|---|
| Goal | The intended outcome. |
| Scope | Files, modules, behaviours or documents in scope. |
| Non-goals | What must not be changed. |
| Constraints | Technical, business, regulatory, security or style constraints. |
| Acceptance criteria | Observable conditions that prove completion. |
| Verification method | How completion will be checked. |
| Risk tolerance | How much uncertainty is acceptable. |
If these inputs are incomplete, the AI should infer conservatively from the repository and surrounding context. If the missing information would make a change risky, the AI must ask the user.
Use this template when giving the AI a task:
Goal:
[What should be achieved?]
Scope:
[What files, modules or behaviours are in scope?]
Non-goals:
[What should not be changed?]
Constraints:
[Frameworks, style, performance, security, regulatory or business rules.]
Acceptance criteria:
[How will we know the task is complete?]
Verification:
[Which tests, checks or inspections should be run?]
Heuristic evaluation is the inspection phase. The AI evaluates the current state against explicit quality dimensions.
A heuristic is a rule of judgment. It does not prove correctness by itself, but it helps identify likely defects, gaps and improvement opportunities.
| Heuristic | Evaluation question |
|---|---|
| Correctness | Does the software satisfy the intended behaviour? |
| Consistency | Does it follow existing codebase patterns, naming and architecture? |
| Simplicity | Is the solution no more complex than needed? |
| Cohesion | Does each module own the right responsibility? |
| Coupling control | Are dependencies explicit, minimal and appropriate? |
| Traceability | Can requirements, code, tests and decisions be connected? |
| Testability | Can the behaviour be verified reliably? |
| Security | Are data, secrets, permissions and trust boundaries protected? |
| Privacy | Is personal or sensitive data minimized, protected and auditable? |
| Robustness | Does the system handle invalid input, edge cases and failures? |
| Observability | Can failures and important state changes be diagnosed? Assess: whether the change introduces or removes structured logging; whether monitoring, alerting and distributed tracing cover the changed code path; whether observability is sufficient for incident response — not merely present; and whether SLO-relevant signals are preserved or introduced where applicable. |
| Maintainability | Will future developers understand and safely change it? |
| Performance | Is it efficient enough for expected use? Assess: latency and throughput implications; memory footprint; database query complexity and index coverage for new or changed query patterns; cache invalidation impact; N+1 query risks; and whether the change introduces a potential performance regression — flag regression risks with the affected code path and regression mechanism. |
| User fitness | Does it support the real user workflow cleanly? |
| Build readiness | Can it be built, deployed and operated without hidden assumptions? |
| Documentation alignment | Do docs, comments and contracts match the implementation? |
Score each heuristic from 1 to 5.
| Score | Meaning |
|---|---|
| 1 | Missing, unsafe or misleading. |
| 2 | Present but weak, inconsistent or risky. |
| 3 | Usable but incomplete. |
| 4 | Strong with minor gaps. |
| 5 | Clear, verified and production-ready. |
Scores must include evidence. A score without evidence is not valid.
The evaluation should produce a scorecard:
Heuristic: Correctness
Score: 3/5
Evidence: Existing tests cover the normal path, but no test covers invalid input.
Risk: Regression may pass CI while still failing edge cases.
Heuristic: Consistency
Score: 4/5
Evidence: Implementation follows existing service pattern; naming differs in one helper.
Risk: Minor maintainability issue.
Gap diagnosis converts weak heuristic scores into concrete findings.
Each gap must answer:
- What is wrong?
- Where is the evidence?
- Why does it matter?
- What risk does it create?
- What would a better state look like?
Gap:
[Specific defect, inconsistency or missing capability.]
Evidence:
[File, test, log, behaviour or documentation reference.]
Impact:
[Why this matters.]
Risk:
[What may fail if left unresolved.]
Desired state:
[What good looks like.]
Use severity to prioritize.
| Severity | Meaning |
|---|---|
| Critical | Data loss, security breach, major outage, regulatory failure or impossible workflow. |
| High | Incorrect core behaviour, serious drift, missing validation or broken build path. |
| Medium | Important gap with workaround or limited blast radius. |
| Low | Cleanup, clarity, naming or minor maintainability issue. |
A remedy is a targeted fix for a diagnosed gap.
Each remedy must include:
- The gap it addresses.
- Files or components likely to change.
- Expected behavioural effect.
- Verification step.
- Risk of unintended consequences.
Remedy:
[Concrete change.]
Addresses:
[Gap identifier or description.]
Change area:
[Files, modules, tests, docs.]
Expected effect:
[What should become true.]
Verification:
[How to prove it.]
Risk:
[Potential side effects.]
- Do not apply a remedy without a diagnosed gap.
- Do not broaden scope unless required to satisfy the goal.
- Prefer existing patterns over new abstractions.
- Add abstractions only when they remove real complexity or match established architecture.
- Update tests when behaviour changes.
- Update documentation when contracts, workflows or configuration change.
- Do not silently change public APIs, database contracts or user workflows.
During implementation, the AI must:
- Read the relevant code before editing.
- Identify existing patterns and follow them.
- Keep changes close to the diagnosed gap.
- Avoid unrelated formatting churn.
- Preserve user changes and uncommitted work.
- Prefer clear, maintainable code over cleverness.
- Add comments only where they clarify non-obvious reasoning.
- Keep migrations, schema changes and API changes traceable.
Verification proves that the remedy worked and did not introduce unacceptable regressions.
- Existing automated tests.
- New focused tests for changed behaviour.
- Type checks.
- Lint checks.
- Build checks.
- Runtime/API checks.
- UI/browser checks.
- Manual inspection.
- Reasoned verification when executable checks are unavailable.
The AI must:
- Never claim tests passed unless they were run.
- Report failing tests honestly.
- Report skipped verification honestly.
- Explain residual risk when verification is incomplete.
- Prefer focused tests over broad fragile tests.
- Add regression tests for fixed bugs where practical.
Verification:
- Command/check: [what was run]
- Result: [passed/failed/not run]
- Evidence: [key output or observation]
- Residual risk: [remaining uncertainty]
Reflection identifies the cause behind the gap.
Useful reflection questions:
- Was the requirement unclear?
- Was the code missing tests?
- Did documentation drift from implementation?
- Did a concept exist in multiple places without one source of truth?
- Did the architecture allow invalid states?
- Did the AI infer something it should have verified?
- Was the change too broad?
- Was a previous fix local when the problem was systemic?
Reflection must produce a lesson. It should not merely restate what changed.
Reflection:
Cause:
[Why the gap existed.]
Pattern:
[Whether this is a one-off or recurring issue.]
Lesson:
[What should be done differently next time.]
Playbook candidate:
[Reusable rule, if applicable.]
The playbook is the reusable memory of the process. It captures rules that prevent repeated mistakes.
- When adding a module, update the data model, API, permissions, tests, documentation and roadmap together.
- When changing a state machine, update states, transitions, API actions, UI labels, tests and documentation.
- When adding a feature flag, define owner module, default state, seed value, UI behaviour and deactivation behaviour.
- When touching authentication or authorization, add adversarial tests.
- When adding a database table, verify tenant scoping, audit columns, soft delete, indexes, migrations and tests.
- When changing an API contract, update OpenAPI, generated clients, tests and consuming UI code.
- When changing a user workflow, verify the UI states, empty states, error states and permissions.
- When using external facts, use primary sources and record the retrieval date when the fact may change.
- When the AI cannot verify a claim, mark it as an assumption or ask for confirmation.
Rule:
[Reusable instruction.]
Applies when:
[Trigger condition.]
Reason:
[Why this prevents defects.]
Required checks:
[What must be verified.]
After remedy and verification, re-score the affected heuristics.
The AI should report:
- Previous score.
- New score.
- Evidence for the change.
- Remaining gaps.
- Whether the acceptance criteria are met.
Example:
Build readiness:
Before: 2/5
After: 4/5
Evidence: Build now passes and missing environment variable is documented.
Remaining gap: Deployment smoke test still not automated.
These rules are mandatory.
- Inspect the repository before making implementation claims.
- Do not invent files, APIs, packages, schemas, commands, tests or system behaviours.
- Do not claim a dependency exists unless it is observed in project files or installed environment.
- Do not claim tests passed unless they were run.
- Do not claim a feature exists unless it was observed in code, tests, documentation or runtime behaviour.
- Use local project sources before memory.
- Use primary external sources for current technical facts.
- Clearly label assumptions.
- Clearly label uncertainty.
- Ask the user when an assumption would be risky.
- Prefer "I found" over "it probably".
- Prefer evidence over confidence.
- Do not fill unknowns with plausible details.
- If verification is unavailable, say so.
Drift happens when related artifacts no longer agree.
When changing behaviour, the AI must check whether the following need updates:
- Requirements.
- Architecture notes.
- Data model.
- Database migrations.
- API contracts.
- Domain rules.
- Permissions.
- Feature flags.
- Configuration.
- UI routes and states.
- Tests.
- Documentation.
- Deployment scripts.
- Monitoring or alerts.
Check:
- Allowed states.
- Allowed transitions.
- Transition guards (conditions that must hold before the transition fires).
- Side effects triggered by transitions (async jobs, notifications, emails, audit events).
- Idempotency of transitions (safe to retry without duplicating side effects).
- Race conditions between concurrent transition attempts from multiple actors or processes.
- API action endpoints.
- UI labels and buttons.
- Permission matrix.
- Audit and notification events.
- Tests.
- Documentation.
Check:
- Change classification: additive nullable, additive required, destructive, rename, type change, index or constraint change, data backfill, query semantics or lifecycle change.
- Migration file, migration ordering and deployment ordering.
- Rollback strategy or explicit forward-fix strategy when rollback is unsafe.
- Model, query layer, repository layer, serializers and API resource mapping.
- Indexes, constraints, uniqueness, foreign keys and performance-sensitive query paths.
- Tenant isolation, authorization filters and row-level access rules.
- Audit columns, timestamps, soft delete, retention and erasure behaviour.
- Seed data, fixtures, factories and local development data.
- Backfill safety, batching, locking, idempotency, expected runtime and retry behaviour.
- Migration tests, model/query tests, data-preservation tests and performance checks where relevant.
- Documentation, release notes, monitoring and operational runbook updates.
- Observability drift: confirm the change does not remove or narrow existing query performance monitoring, error alerting, tracing or SLO coverage.
Check:
- Change classification: additive compatible, breaking contract, same-schema behaviour change, error/status change, authentication/rate-limit change or deprecation/versioning change.
- Route definitions, handlers, middleware and permission checks.
- Request schema, validation, examples and malformed-input handling.
- Response schema, status codes, headers, pagination, sorting and filtering semantics.
- Error model, error codes, retry semantics and client-visible messages.
- OpenAPI or equivalent contract documentation.
- Generated clients, SDKs, typed callers, mocks and fixtures.
- Front-end consumers, internal service consumers and external integrations.
- Backward compatibility, versioning, deprecation notes and migration guidance.
- Contract tests, integration tests, negative-path tests and authorization tests where relevant.
- Observability, logs, metrics, alerts and dashboards for changed API behaviour; confirm the change does not remove or narrow existing monitoring, alerting, tracing or SLO coverage.
Check:
- Whether API shape exposes a new or changed persistence concept.
- Whether database nullability, defaults and constraints match API validation.
- Whether API authorization and database tenant isolation enforce the same boundary.
- Whether API pagination, filtering and sorting match new indexes and query behaviour.
- Whether migration ordering supports deployed API versions during rollout.
- Whether old clients can safely operate during and after migration.
- Whether backfills or feature flags are needed before exposing new API behaviour.
- Whether tests cover API behaviour before, during and after the schema change.
Check:
- Loading state.
- Empty state.
- Error state.
- Permission-restricted state.
- Partial state (some data loaded while other data is still loading or unavailable).
- Offline or degraded-connectivity state.
- Optimistic-update state and rollback path if the server rejects the action.
- Concurrency state (conflict or merge behaviour when multiple actors edit simultaneously).
- Mobile and desktop layout.
- Accessibility.
- Data refresh behaviour.
- Tests or screenshots.
Check:
- Change classification: authentication/session, authorization/policy, tenant isolation, secrets/credentials, sensitive data, logging/telemetry, audit/compliance, admin/impersonation or break-glass.
- Role and permission matrix, policy definitions and deny-by-default behaviour.
- Allow paths, deny paths, cross-tenant attempts and privilege-escalation cases.
- Tenant/workspace/org scoping in APIs, database queries, background jobs, caches, search indexes, queues, exports and admin tooling.
- Secrets, credentials, tokens, keys and cryptographic material handling.
- Sensitive-data collection, minimization, masking, encryption, retention, erasure and export controls.
- Logs, metrics, traces, analytics, screenshots and error reports for secret or sensitive-data leakage.
- Audit trail: actor, subject, action, timestamp, correlation ID, before/after values, source IP/device where relevant and tamper-resistance expectations.
- Abuse cases, adversarial tests, authorization tests, isolation tests and regression tests.
- Security/privacy documentation, operational runbooks, alerts and incident response notes where relevant.
Check:
- Data classification: personal data, sensitive personal data, secrets, customer confidential data, operational metadata or anonymous/aggregate data.
- Data purpose, minimization, consent/legal basis and user-visible privacy notice where relevant.
- Data flow across client, API, database, logs, analytics, AI tools, exports, backups and third-party processors.
- Access controls for read, write, export, delete, support access and administrative access.
- Retention, deletion, erasure, anonymization and backup behaviour.
- Masking/redaction in UI, logs, traces, screenshots, emails, exports and support tooling.
- Test data, fixtures, recordings and screenshots avoid real sensitive data.
- Privacy review, data-protection documentation and release notes where relevant.
Check:
- Logs contain enough diagnostic context without secrets or unnecessary sensitive data.
- Audit events capture actor, subject, action, result, timestamp, correlation ID and relevant before/after values.
- Failed authorization, denied access, admin actions, exports, deletes and permission changes are auditable where required.
- Audit records are protected from tampering and have clear retention.
- Monitoring and alerts cover high-impact security/privacy failures.
- Incident response or operational runbooks are updated when audit/logging behaviour changes.
When a change has a non-trivial release or operational footprint, the AI must classify the change before acting:
- Deployment of a new or changed service, worker or scheduled job.
- Feature-flag addition, change or removal.
- Configuration change: new environment variable, removed variable, value change or infrastructure/IaC change.
- Rollout strategy change: canary, blue/green, dark launch, staged rollout or full rollout.
- Migration with a deployment ordering constraint.
- Monitoring, alerting or on-call runbook change.
Then check and align:
- Deployment ordering: confirm that services, migrations and feature flags are activated in the correct sequence and that the system is safe at every intermediate state.
- Rollback or forward-fix strategy: classify whether rollback is safe, partially safe or unsafe. If unsafe, state the forward-fix plan and residual risk explicitly.
- Feature-flag lifecycle (if applicable): owner/module, default state, seed or fixture value for test environments, activation behaviour, deactivation behaviour, UI/API behaviour under each flag state, documentation and cleanup plan.
- Configuration alignment: classify the configuration change, confirm documentation is updated, confirm local/staging/production alignment where known, confirm secret rotation is addressed if secrets are involved and confirm deployment scripts and operational runbooks reference the new configuration.
- Smoke test scope: define which critical workflows must be exercised immediately after deployment; confirm the smoke test is scoped, executable and assigned.
- Monitoring and alert readiness: confirm a health-check endpoint or equivalent is in place, confirm an error-rate or latency alert covers the changed workflow and confirm the alert threshold is appropriate.
- On-call and runbook alignment: confirm the on-call runbook reflects the change, including triage steps, rollback commands and escalation contacts where relevant.
- Incident-response notes: for high-risk releases, add a brief incident-triage note covering the most likely failure modes and their remediation steps.
- Release notes: confirm that operators and relevant stakeholders know what changed, how to verify success and how to roll back.
Do not treat a release or operations change as complete until deployment ordering, rollback strategy, configuration alignment, smoke test scope, monitoring readiness and runbook alignment have been considered. If any item cannot be verified, record the assumption and residual risk.
When adding, removing, updating or auditing a dependency — including packages, libraries, services, SDKs, build tools, container base images, infrastructure modules and transitive dependencies — classify the change before acting:
- New dependency added.
- Existing dependency version updated (patch, minor or major).
- Dependency removed or replaced.
- Lockfile refresh or regeneration without version intent change.
- Transitive dependency change (indirect version pinned, forced or unpinned).
- Build tool, compiler, runtime or base image change.
- Supply-chain configuration change (registry, mirror, checksum policy, SBOM tool).
Then check and align:
- Justification: the dependency is necessary and no existing project dependency already provides the capability.
- License acceptability: license is identified, compatible with project obligations, and any copyleft, commercial restriction or ambiguous license is flagged.
- Known CVE and vulnerability status: the dependency version has been checked for known CVEs or advisories; severity, reachability and mitigation are stated if a vulnerability exists.
- Lockfile consistency: the lockfile is updated and committed with the change.
- Provenance and registry trust: the package is fetched from the expected registry, checksum or signature is verifiable, and there are no known dependency-confusion or typosquatting risks.
- Transitive dependency impact: significant transitive dependency changes are identified; new transitive dependencies with license or CVE concerns are flagged.
- Build and test reproducibility: the build is reproducible with the updated dependency and no unintended floating version reference was introduced.
- Test coverage after the change: relevant tests were run after the dependency change and no new failures were introduced.
- Documentation and configuration alignment: dependency documentation, manifest comments, architecture records or onboarding guides updated where the change affects build setup, tooling or system design.
- Release and operational impact: runtime environment, container image, deployment configuration or supply-chain security control impact is identified and the release plan accounts for it.
Do not treat a dependency change as complete until license, CVE status, lockfile consistency and test confirmation have been addressed. If CVE status cannot be verified or a license is ambiguous, record the assumption and residual risk.
When a change triggers the need to create, update, supersede or deprecate an architecture record, classify the record action before acting:
- New record: a material architecture decision is being made for the first time.
- Update to an existing record: an existing decision changes in scope, constraints, rationale or consequences without being superseded.
- Supersession: a new decision replaces a prior decision; the old record must be linked and marked superseded.
- Deprecation or removal: a prior decision is retired because it is no longer applicable.
Then check and align:
- Trigger verification: the change meets the threshold for an architecture record (affects system shape, integration contracts, security model or long-term ownership, not merely a minor implementation detail).
- Existing records searched: prior decisions in this area are identified and confirmed still valid, or marked as contradicted/superseded.
- Decision context: date, participants, constraints and forces that made the decision necessary are recorded.
- Problem statement: the architectural problem being solved is stated clearly.
- Options considered: alternatives evaluated are listed with reasons for rejection; if only one option was considered, this is stated and explained.
- Decision: the chosen approach is stated clearly and unambiguously.
- Consequences: positive and negative consequences, trade-offs and accepted technical debt are recorded.
- Affected systems, modules and teams: impacted parts of the codebase, integrations and teams are identified.
- Cross-references: related records, API contracts, data model documents, security review findings or deployment plans are linked.
- Supersession link: if this record supersedes a prior one, the old record has a supersession notice and the new record links to the old one.
- Storage and discoverability: the record is in the expected location and named consistently with the project convention.
- Review status: for high-consequence decisions, the record has been reviewed by relevant stakeholders.
Do not treat an architecture-affecting change as complete until existing records have been searched, the decision rationale and consequences are captured, and supersession or cross-references are resolved. If an architecture record is deferred, record the assumption and the plan to complete it.
For autonomous AI development work, the AI should follow this sequence:
- Restate the goal and acceptance criteria.
- Inspect relevant files, tests and documentation.
- Identify constraints and non-goals.
- Build a heuristic scorecard for the current state.
- Diagnose gaps and rank them by severity.
- Select the smallest sufficient remedy set.
- Explain the intended changes before editing when the work is substantial.
- Implement the remedy.
- Run verification.
- Fix verification failures that are in scope.
- Re-score affected heuristics.
- Reflect on root causes.
- Propose or update playbook rules.
- Report the outcome, verification and residual risks.
A task is complete only when:
- Acceptance criteria are met.
- No known critical or high-severity in-scope gap remains.
- Verification has passed or residual risk is explicitly disclosed.
- Changes are traceable to the stated goal.
- No unrelated changes were introduced.
- Assumptions are named.
- Drift checks were performed for affected artifacts.
The AI is authorized to act without asking when:
- Reading, inspecting and analyzing files, tests, logs and documentation.
- Running non-destructive checks: tests, type checks, lint, build commands.
- Applying remedies that are fully within the stated scope and have a clear acceptance criterion.
- Making implementation decisions that follow established project patterns with no ambiguity.
- Reporting findings, scores, gaps, assumptions and residual risks.
- Asking clarifying questions when inputs are incomplete.
Everything outside this boundary requires either human confirmation or explicit labeling as an assumption with disclosed risk.
The AI must stop immediately and ask before proceeding when:
- Requirements conflict.
- The task brief contains internally conflicting acceptance criteria.
- A change may alter security, privacy, legal or regulatory posture.
- A destructive operation is required.
- Production data or irreversible migration is involved.
- Completing the goal requires expanding scope beyond the stated task brief.
- A proposed remedy requires changing a system or file the AI cannot inspect or verify.
In an unattended or async context where no human is reachable, treat all escalation triggers as hard stops.
The AI completes the current file edit or discrete step, then pauses before continuing when:
- Desired behaviour cannot be inferred safely.
- External facts are needed and cannot be verified.
- Multiple reasonable product behaviours exist and choosing one would materially affect users.
The AI may proceed when minor ambiguity does not affect security, data or core behaviour, provided it labels the assumption explicitly, flags it for human review in the final report, and does not treat the task as complete until the flag is resolved.
When an escalation trigger fires during task execution, the AI must:
- Complete the current atomic unit of work. Do not leave a file in a half-edited state.
- Do not start any new file or action that is part of the blocked next step.
- Write a handoff note covering: what steps were completed, what triggered the escalation, what information is needed to proceed, and what the safe state of the work is now.
- If partial changes exist across multiple files, report the partial state clearly and do not commit partial work without labeling it as partial and blocked.
- Do not claim the task is complete. Do not claim verification passed for incomplete work.
Every AI development cycle should end with:
Outcome:
[What was accomplished.]
Changes:
[Files or components changed.]
Verification:
[Checks run and results.]
Heuristic delta:
[Scores improved or remaining weak areas.]
Residual risks:
[Known limitations or unverified areas.]
AI participation:
[AI system and model used; scope of involvement; human review performed. Write "Not applicable"
if the output will not be submitted externally or used in a regulated or high-stakes context.]
Playbook lessons:
[Reusable rules learned.]
For very small tasks, use this shortened loop:
1. Confirm goal.
2. Inspect relevant code.
3. Identify gap.
4. Apply focused remedy.
5. Verify.
6. Report result and residual risk.
Even in the minimal version, the AI must still follow the anti-hallucination and anti-drift rules.
Use this prompt at the start of an AI-assisted software task:
Use the Heuristic Evaluation-Remedy-Reflection Loop.
Goal:
[state the goal]
Scope:
[state the scope]
Non-goals:
[state what must not change]
Acceptance criteria:
[state how success will be proven]
Instructions:
- Inspect the repository before making claims.
- Separate facts from assumptions.
- Diagnose gaps before proposing remedies.
- Make the smallest sufficient change.
- Verify with tests or checks.
- Report residual risk.
- Update the playbook if a reusable lesson appears.
The distributable bundle adds a governed multi-cycle runner for requests such as
run eval 30 cycles. Thirty is a maximum, further bounded by elapsed time, diff size, external
cost and project limits; it is never a quota to manufacture changes.
Before the first remedy, the project must have a live goal, loop instance, scorecard, playbook and
schema-2 HERR_Cycles/cycle-ledger.jsonl. Terms, gaps, gates and tripwires use stable TERM-*,
GAP-*, GATE-* and TRIP-* IDs. Each term records unit, baseline, current value, target,
direction, minimum meaningful change, uncertainty, source and observation date. Heuristic
applicability is locked by an owner-approved decision so the score denominator cannot drift.
Adoption also records who authorizes a cycle's checkpoint, what that authorization covers and what it excludes. A registration requires a resolvable checkpoint reference while committing needs separate authority, so the two hold together only once that decision is written down.
Each run and cycle is claimed atomically. The ledger state machine permits one start and closure per run, one immutable registration per cycle and exactly one outcome or abandonment. A registration records actor, lease, checkpoint, lever, prediction, falsifier, gates and tripwires before editing. Interrupted work is resumed or abandoned through recovery events, never repaired by rewriting ledger history.
The outcomes are:
improved— movement exceeds the registered threshold after uncertainty, gates pass and no tripwire worsens that the registration did not declare as an accepted cost;baseline-established— a previously unmeasured term gains a valid baseline without claiming improvement;gap-closed— a diagnosed gap closes on evidence through a lever that has no numeric target, while the target term does not move meaningfully;no-change,worsened,unmeasurableorblocked— retained as first-class evidence.
A lever that is known in advance to degrade an invariant the cycle also registers names that tripwire in the registration as an accepted cost, with a reason and a gap carrying the remaining work. A degradation declared that way does not disqualify a positive outcome; one that was not declared still does, and is the case tripwires exist for. The declaration must precede the first remedy edit, while the result is still unknown, and it can never cover every registered tripwire.
Neither baseline establishment nor gap closure counts toward exhaustion. A run that finishes the
work it registered, below its cycle budget and with nothing unresolved, stops as scope-complete.
Three no-change/unmeasurable outcomes,
all levers parked, a gate/owner wall, degradation, a resource limit, goal completion or exhausted
cycle budget stops the run early.
Every remedy also has a disposition: accepted, reverted, retained with an independent justification, or isolated pending an owner. A worsened remedy returns to the safe checkpoint when feasible. Gates and passing tests are necessary evidence but do not prove that the objective term moved.
Software that scores, ranks, recommends or makes automated decisions must name and version the model, preserve input provenance, justify weights/thresholds, reproduce historical outputs and explain decisions from stored inputs. Calibration at one point in time is insufficient: decisions must be compared with real outcomes against a baseline, and that outcome feedback must feed a governed recalibration path. If outcomes cannot yet be measured, record the feedback path as a gap instead of claiming that the model learns.
HERR's own 1–100 heuristic scores are ordinal diagnostics. Projects define evidence anchors and normally use five-point increments. Completion depends on term targets, individual thresholds, gaps, gates and tripwires; an average cannot conceal a severe gap or an applicability change.
The HERR Loop is a strong best-practice pattern for AI-assisted software development because it addresses the main weaknesses of AI coding workflows:
- Hallucinated implementation details.
- Overconfident claims.
- Unscoped changes.
- Documentation drift.
- Untested remedies.
- Repeated mistakes.
- Weak traceability between goal, change and verification.
It should not be treated as the only development process. It is most effective when combined with normal engineering controls: tests, review, CI, version control, security review and disciplined release management.
The best use of the HERR Loop is as a mandatory operating loop for AI agents working inside a real software repository.