Loop Engineering: Designing the System, Not the Prompt

The operating rules that keep the loop honest. Rule 4 matters most — it is what stops the agent from making tests pass by weakening them.

# Loop rules
Each loop iteration:
1. Read END_STATE.md, TASKS.md, and TEST_PLAN.md before touching code
2. Make one small improvement per loop — the smallest useful step
3. Run tests after every change
4. Never modify or delete a test to make it pass
   If a test looks wrong, stop and ask — do not "fix" the test
5. Update TASKS.md before finishing:
   what changed, what failed, what is next
6. Commit only when tests pass locally
7. If the same test fails 3 loops in a row, stop and report
8. Never mark a criterion done without evidence:
   a passing test, or an explicit review

The human-readable measurement strategy. Tests turn "does it work?" into a yes/no signal. And cases are cheap: for a calculator, one table of inputs and expected outputs generates dozens of tests — coverage of the requirements is the goal, not the count.

# Test Plan
Test:
- Standard tax calculation
- Quantity greater than 1
- Zero tax
- Decimal tax rate
- Discount before tax
- Rounding edge cases
- Negative price
- Invalid quantity
- Tax rate above 100
- Discount above 100

Success condition:
All tests pass locally and in GitHub Actions.

Who writes the tests — and how do you know they're the right ones? You describe what matters in plain language (this test plan is exactly that); the agent turns each line into a test; the final end-state review catches whatever the tests missed. You never have to write test code to direct the loop — but someone does have to judge whether the tests are honest.

For the engineers: a passing test only proves the code does what the test says — not what the requirement needs. Watch for tests that can't fail (asserting a value against itself, or re-deriving the expected result with the same code being tested), tests pinned to whatever the code happened to return rather than to the spec, and "coverage" that runs a line without checking its output. A good test states the expected answer independently — expect(tax(100, 0.08)).toBe(8.00), a number you worked out by hand — so that when the code is wrong, the test goes red. "The agent wrote a test" is not the same as "the requirement is covered." Reviewing tests against END_STATE.md is a real job, and on the loop it is mostly yours.

The project's memory. Without it, every loop starts from zero.

# Task Log

## Backlog
- [ ] Create calculation function
- [ ] Add unit tests
- [ ] Build input form
- [ ] Add validation
- [ ] Add GitHub Actions
- [ ] Final review against END_STATE.md

## Completed
- [x] Project initialized
- [x] END_STATE.md created
- [x] LOOP.md created

## Failed Tests / Issues
None yet.

This tells GitHub: whenever new code is pushed, install the project and run the tests. It re-runs tests Claude already ran because a clean machine catches problems that only appear outside your setup — and the result is recorded next to every commit, in the repository’s Actions tab.

name: Run Tests
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Check out code
        uses: actions/checkout@v4
      - name: Set up Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
      - name: Install dependencies
        run: npm install
      - name: Run tests
        run: npm test

One prompt runs one loop iteration. Notice it points at documents, not at your memory of the conversation.

Read END_STATE.md, LOOP.md, TASKS.md, and TEST_PLAN.md.
Inspect the current codebase.
Identify the biggest gap between the current state
and the desired end state.
Choose the smallest useful improvement.
Implement it.
Run tests.
If tests fail, diagnose and fix them.
Update TASKS.md.
Tell me what changed and what the next loop should do.

A fictional failure, straight from the test runner:

FAILED: should round final total to 2 decimal places
Expected: 21.65
Received: 21.64875

This is not just an error. It is a feedback signal. The signal says:

• The current state does not satisfy the rounding requirement
• The calculation logic needs correction
• The test should remain as a guardrail
• Claude should fix the smallest relevant part of the code

A failure doesn't break the loop — it drives it. The cycle below runs until the signal turns green.