work-loop

name	work-loop
description	Use this skill whenever you're implementing a non-trivial change — a phase of the build plan, a bug fix touching more than one file, a refactor, or anything driven by a conformance case. Enforces the plan → execute → gates → review loop with mechanical verification. Default to this skill for any task larger than a one-line edit.

Skill: work-loop

This is the project's standard inner loop for non-trivial work. It exists because LLM self-assessment is unreliable: agents declare victory when they feel done, not when objective gates pass.

When this skill applies

• Implementing a phase or subphase from docs/PLAN.md.
• Adding conformance cases and the Rust that makes them pass.
• Bug fixes touching more than one file.
• Refactors.
• Any task where you'd otherwise be tempted to "just go".

For genuine one-line edits (typo, config tweak), skip the loop.

The loop

   ┌─────────────────────────────────────────────────────────┐
   │                                                         │
   ▼                                                         │
PLAN  ──►  EXECUTE  ──►  GATES  ──►  REVIEW  ──►  DECIDE    │
                          │           │            │         │
                          │           │            └── findings? ──┐
                          │           │                            │
                          └─ failed? ─┴── findings? ────── fix ────┘
                                                              │
                                                              └── back to GATES

1. PLAN — think before acting

• Read the relevant phase section in docs/PLAN.md. That section is the work-breakdown — don't invent your own.
• Write down: which files you'll touch, which conformance cases will turn green, and what you are not changing. Three sentences is enough.
• For architecturally significant work, use Plan Mode (Shift+Tab twice in Claude Code) and add "think hard" or "ultrathink" to your prompt.

The output of this step is a written plan you can return to. Don't keep it in your head — your context will turn over and you'll lose it.

2. EXECUTE — make the change

Implement the smallest coherent unit toward the goal. Resist fixing unrelated things you notice along the way — note them for later. For formula behavior: write the YAML conformance case first, then the Rust. This is not optional.

3. GATES — mechanical verification

Run in order. Only proceed if each passes:

cargo fmt --all --check                                    # style
cargo clippy --workspace --all-targets -- -D warnings      # correctness
cargo test --workspace                                     # behavior + conformance corpus

If a gate fails, go to FIX. Don't move past a failing gate by editing the gate.

4. REVIEW — adversarial self-review

After gates pass, run the spec-reviewer subagent:

Use the spec-reviewer subagent to review my changes against
docs/PLAN.md phase <N> and the conformance cases I added.

The subagent reads adversarially — it's looking for what you missed. Findings come back grouped by severity (Blockers, Concerns, Questions).

For spec-less changes (a refactor, say), self-review against this checklist:

• Does the diff match the plan you wrote in step 1? Note divergences.
• For each touched function: is test/conformance coverage no worse than before?
• Did anything outside the planned scope get touched? Why?
• What's the dog that didn't bark — what should have changed and didn't?

5. DECIDE — fix or finish

• Blockers → go to FIX, then re-run GATES and REVIEW.
• Concerns → fix what you can in this PR; capture the rest as follow-up.
• Gates green and review clean → done. Open the PR.

FIX phase

1. Read the finding carefully. Fix what the reviewer actually flagged, not the symptom.
2. Make the smallest change that addresses it.
3. Re-run GATES.
4. Re-run REVIEW only if the fix touched logic the reviewer hadn't approved.

Termination — when to stop iterating

Stop when any of these is true:

1. Gates green AND review clean — the normal exit. Ship.
2. Same finding two iterations in a row — you're going in circles. Surface it to a human.
3. Diff is shrinking but findings aren't — stop and rethink the approach.
4. Iteration cap reached — default 5 in-session iterations. If you hit the cap, the task is bigger than you thought. Stop, write what you learned, re-plan.

Never silently expand scope to make a finding go away.

Capture what was learned

Before opening the PR, ask: what would have made this loop go faster?

• "I had to grep for <thing> repeatedly" → add a pointer in AGENTS.md.
• "The conformance case format for <edge> wasn't obvious" → add an example to the relevant tests/conformance/cases/ YAML file comment.
• "I made the same wrong assumption twice" → add a note to AGENTS.md so the next session doesn't repeat it.
• "This workflow is now the third time I've done it" → propose it as a new skill in .claude/skills/.

Anti-patterns to refuse

• Skipping PLAN because "the task is small." If it's truly small, the plan is one sentence — write it anyway.
• Writing Rust tests for formula behavior instead of YAML conformance cases. Rust tests for formula math are a convention violation.
• Editing a conformance case to pass instead of fixing the implementation. The corpus is the oracle; lying to the oracle defeats the project.
• Declaring victory because gates pass. Gates are necessary, not sufficient. Review catches what gates can't.