Torus Engineering in Practice

§1Quick Start (3 minutes)¹

1. Locate your execution loop. You already have one: fixing CI, handling issues, opening PRs — the thing you go around every day is the first circle (the meridian). Additional work required: none.
2. Install an improvement loop. Create one recurring calendar event titled “Review how the agents are run (30 min).” That is your second circle (the longitude). It is topologically essential that this exists as a calendar event, not as good intentions.
3. Take the product. Do nothing. As long as the two loops wind independently, the product S¹ × S¹ forms on its own. This step is handled by topology; no additional dependency is required.

That is the entire installation. Everything below is for reading after it works.

§2Copy-Paste Files

For readers who want only the conclusions, here are two files you can paste as-is. The first appends to CLAUDE.md; the second winds the longitude. Adjust the numbers to taste, but do not change the structure (two loops, mutually independent).

## Torus Operating Rules

### Execution loop (meridian)
- If CI is red, fix it. If an issue arrives, handle it. If you open a PR,
  see it through.
- After each revolution, increment the number in `.torus/revolutions`.

### Improvement loop (longitude)
- Whenever `.torus/revolutions` reaches a multiple of 100, stop fixing the
  loop's work and fix the loop **itself**:
  1. Name three failure patterns from the last 100 revolutions
  2. Revise at least one thing in this CLAUDE.md
  3. Delete one Skill nobody uses (a brief eulogy is optional)
- Do not improve the improvement loop from inside the improvement loop
  (genus 2 ships in the next major version).

### Forbidden
- Do not fill the hole. The moment everything is automated, the torus
  degenerates to a sphere and you are back in the 4th generation (§4 of
  the paper). Always keep one cavity through which human judgment passes.

# The longitudinal circle. Winds independently of the meridian (your usual CI).
name: improvement-loop
on:
  schedule:
    - cron: "0 9 * * 1"   # tune your winding ratio here (see Table 1)
  workflow_dispatch:        # the hole through which human judgment passes. Do not seal.
jobs:
  wind:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Revise the execution loop itself
        run: |
          echo "Aggregate recent failure patterns; open a PR revising CLAUDE.md"
          # Put your favorite agent CLI here. There is one rule:
          # this job must not touch product code. The moment it does, it is
          # the execution loop, the longitude collapses onto the meridian,
          # and your genus drops to 0.

§3Choosing a Winding Ratio (Cheat Sheet)

The winding ratio — how many revolutions of the execution loop per revolution of the improvement loop — is the only tuning parameter in torus engineering. When in doubt, use 100 : 1.

§4Troubleshooting

§5Adoption Checklist

• The execution loop is running (i.e., you are doing your job)
• The improvement loop exists on a calendar (as an event, not as hope)
• You have chosen one winding ratio and can say it out loud (“we run 100 to 1”)
• The improvement loop changes the execution loop, and does not do the execution loop’s work
• There is a hole (a human exercises judgment in at least one place)
• A doughnut has been procured (optional; recommended)

Four checks out of six and your system is topologically a torus. The remaining two will be improved on the next trip around the longitude. That is the nice thing about this method.

§6Glossary

Provided in case you must converse with the authors of the paper.

§7Frequently Asked Questions (Practical)

Do I need to read the paper?

No. That is what this page is for. Note, however, that on a torus the state “hasn’t read it” eventually winds back around to “has read it.”

Does it work if I just copy-paste?

The act of copy-pasting was one revolution of the execution loop. It is already working.

How do I explain this to my manager?

Try “it is the product of a loop and a graph.” If that fails, “the adoption cost is one doughnut” (paper, §5) will succeed.