{
  "version": "act 2.0.0",
  "slug": "create-work-loop",
  "name": "create-work-loop",
  "description": "Generate a robust, idempotent work-loop tracker \u2014 the single resumable state file that drives a large implementation program through plan \u2192 implement \u2192 review cycles with self-tracking, found-issue capture, and remediation discipline. Use whenever the user wants to execute a large or multi-item implementation systematically; triggers include \"create a work loop\", \"set up a tracker\", \"make this resumable\", \"execution harness\", \"work through this spec item by item\", or any time one or more approved specs need to be implemented across many sessions or by many agents and progress must survive context loss. Also drives and resumes the **quality loop** \u2014 a.k.a. \"continuous quality\", \"the quality ratchet\", \"the architecture ratchet\" \u2014 which maps to the architecture-audit \u2192 architectural-refactoring \u2192 verify-refactor skill cycle; triggers include \"run the quality loop\", \"set up a quality ratchet\", \"keep auditing and refactoring\", \"continuously improve architecture\".",
  "url": "https://act101.ai/docs/skills/create-work-loop",
  "body_md": "# Create Work Loop\n\nA work loop is one markdown file that is the **entire resumable state** of an implementation program. Any session \u2014 tomorrow, after a crash, a different agent \u2014 continues the program with a single instruction: *\"resume the work in `<tracker path>`\"*. Nothing about progress lives in conversation memory, plans-in-flight, or anyone's head; if it isn't in the tracker (or in a plan file the tracker points to), it didn't happen.\n\nThe design rests on one separation of powers, and everything else follows from it:\n\n- **Specs own acceptance.** What \"done\" means for every item lives in spec documents. The tracker never restates or overrides spec content \u2014 restating invites drift, and drift between two sources of truth is how programs rot.\n- **The tracker owns ordering and state.** Which item is next, what state each is in, where its plan lives, which commits closed it.\n- **Plan files own fine-grained progress.** Checkboxes inside each item's implementation plan are the resume state *within* an item; the tracker is the coarse state *across* items.\n\n## Process\n\n### 1. Gather inputs (from context first)\n\nMost inputs are usually already in the conversation or repo. Derive what you can; ask only for what's genuinely missing, one question at a time.\n\n| Input | Source | Notes |\n|---|---|---|\n| Authority spec(s) | The approved spec docs this program implements | Required. More than one is fine \u2014 the tracker lists the authority chain. |\n| Tracker path | User preference or project convention | Default `docs/specs/<program>-work-loop.md`. Check for existing work-loop files to match local convention. |\n| Queue items | Spec sections/items, in execution order | One row per independently closeable unit. If the spec has explicit IDs (E1, R3\u2026), reuse them; otherwise mint a short prefix per phase. |\n| Ordering & dependencies | Spec dependency notes, user decisions | Record them as a note under the queue, not as prose scattered through rows. |\n| Verification floor | Project test/lint/build commands (CLAUDE.md, CI config, justfile) | Per surface if the program spans surfaces (e.g., cargo for crates, vitest for a worker, repo checks for an action). |\n| Project hard rules | The project's CLAUDE.md | Inherit **verbatim** \u2014 never invent rules the project doesn't have, never drop ones it does. |\n| Exclusions | Anything from a sibling work loop that does NOT apply here | Name exclusions explicitly (e.g., \"scan-score tracking excluded \u2014 specific to the remediation loop\"). Silent omission looks like an oversight; named exclusion is a decision. |\n| Workspace rules | Branch/worktree/concurrency facts | E.g., \"work stays on the current branch; a concurrent agent shares this checkout \u2014 wait out lock contention.\" Branch/merge/PR decisions belong to the user unless they have said otherwise. |\n\n### 2. Generate the tracker\n\nRead `references/tracker-template.md` and instantiate it with the gathered inputs. The template is the contract \u2014 every section in it exists because a failure mode demanded it (the template annotates which). Keep all sections; tailor their contents.\n\nSeed the queue completely: every item from the authority specs gets a row at creation time, even far-future ones. A complete queue is what makes \"find the first non-DONE row\" a total resume algorithm \u2014 gaps force the resuming session to re-derive scope from the specs, which is exactly the context-dependence the tracker exists to eliminate.\n\n### 3. Commit\n\nCommit the tracker as its own change (or together with the state change it records \u2014 never apart from one). The tracker's credibility rests on one invariant: **it is never stale relative to committed work**. That invariant starts at the first commit.\n\n## Idempotency (re-running this skill)\n\n`/create-work-loop` against a program whose tracker already exists must be safe. Never clobber. Reconcile instead:\n\n1. Read the existing tracker fully.\n2. **Never regress state** \u2014 a row's state only moves forward here; only the resume protocol (executing real work) moves states.\n3. **Add missing rows** for spec items that have no row (new spec amendments since creation), appended in spec order with a dated Log entry naming what was added and why.\n4. **Never delete rows** \u2014 a row that no longer applies is `DROPPED(evidence)`, which preserves the audit trail.\n5. Report drift you noticed but did not change (e.g., a row whose plan file is missing) rather than silently \"fixing\" it.\n\n## What the generated protocol guarantees\n\nThese are the load-bearing behaviors the template encodes \u2014 understand them so you can adapt wording without breaking them:\n\n- **Plan \u2192 implement \u2192 review per item.** `TODO` rows get a written plan (via the project's planning skill if present) before any code; `PLANNED` rows execute the plan with checkboxes ticked as they complete; before an item closes, its changes get a review pass, and review findings are either fixed in-item or captured as F-rows \u2014 never noted-and-ignored.\n- **Premise re-verification.** Specs record a baseline that drifts. Resuming sessions verify the spec's premises against live code before acting, and record drift as a dated spec amendment. This is the defense against confidently implementing against a world that no longer exists.\n- **Found-issue discipline.** Any defect discovered mid-item is in scope \u2014 nothing is \"pre-existing\", nothing is parked in a follow-ups list. Blocking issues are fixed inside the item; non-blocking ones get a dated spec amendment plus an `F-n` queue row carrying the same closing discipline as planned rows. This is what keeps a long program from accumulating a shadow backlog nobody owns.\n- **Evidence-gated closing.** A row reaches `DONE` only when every acceptance criterion in its spec section passes **with shown output** \u2014 the verification floor actually run, not asserted. \"It should pass\" closes nothing.\n- **Same-commit state updates.** The queue row changes in the same commit as the work it records. This is the idempotency anchor: any interruption leaves the tracker accurately describing the last committed state.\n- **One item at a time.** An item fully closes before the next begins. Parallelism, when wanted, is a user decision recorded in the tracker's ordering notes \u2014 not an agent improvisation.\n\n## Variant: the quality loop (the architecture ratchet)\n\nWhen the request is a **quality loop** / **continuous quality** / **\"run the quality loop\"**, the program being driven is not a written spec \u2014 it is the **architecture ratchet**: a continuous `architecture-audit` \u2192 `architectural-refactoring` \u2192 `verify-refactor` cycle that lifts structural health one notch per pass and never lets it slide back. Everything in this skill still applies; only the *source of acceptance* and the *queue lifecycle* specialize. Reach for this variant when the user wants ongoing structural quality, not a fixed feature list.\n\n**REQUIRED SUB-SKILLS** \u2014 the loop *invokes* these, it does not reimplement them:\n- `architecture-audit` \u2014 produces `report.md` + `project-map.md`; owns the Refuted & Re-characterized ledger and the improving/stable/degrading trend verdict.\n- `architectural-refactoring` \u2014 executes confirmed findings, commits each step, appends to `remediation-log.md`.\n- `verify-refactor` \u2014 the per-change behavior-preservation gate (SAFE / REVIEW / UNSAFE / UNKNOWN).\n\n### Same separation of powers, different sources\n\n| Generic work loop | Quality-loop instance |\n|---|---|\n| Specs own acceptance | **The audit `report.md` + `project-map.md` own acceptance.** A finding is \"done\" only when a re-audit's fresh structural evidence confirms it resolved \u2014 never on an agent's assertion. The tracker points to finding IDs; it never restates the finding. |\n| Tracker owns ordering & state | **Tracker owns the cycle number + current phase** (AUDIT \u2192 REMEDIATE \u2192 RE-AUDIT) and which findings are open this cycle. |\n| Plan files own fine-grained progress | **`remediation-log.md` owns per-finding progress** \u2014 the append-only ledger keyed to finding IDs is the equivalent of a plan file's checkboxes. |\n\nThe durable cross-session state is therefore three artifacts in concert \u2014 `project-map.md` (current structural state), `remediation-log.md` (actions taken), and the work-loop tracker (which cycle/phase we're in). *\"Resume the quality loop in `<tracker>`\"* rehydrates entirely from these; nothing lives in conversation memory.\n\n### The queue is regenerated, not seeded upfront\n\nUnlike a spec-driven loop where every row exists at creation, the quality-loop queue is **produced by each audit pass**: one row per *confirmed actionable* finding in the latest `report.md`, in remediation priority order (cycles > god classes > high coupling > dead code). In the queue table, the generic `Spec \u00a7` column becomes **`Finding ID + report ref`**. Refuted / re-characterized entries never become rows \u2014 that is the ratchet's lower pawl: a smell investigated and disproven is recorded in the map's Refuted ledger and never re-flagged.\n\n### Running it (\"run the quality loop\")\n\nIf no quality-loop tracker exists yet, generate one (the normal job of this skill, specialized per the table above) before driving the cycle. Then:\n\n1. **AUDIT.** Invoke `architecture-audit`. Record the cycle number; seed the queue with its confirmed findings by ID. If the audit surfaces *no* confirmed actionable findings (only refuted / re-characterized remain) and the trend is stable, the ratchet is at its current floor \u2014 stop and report. Do not invent work or re-open refuted smells.\n2. **REMEDIATE.** For each finding row, in priority order: invoke `architectural-refactoring` for that finding (it plans along seams, executes, re-runs the specific analysis, commits, appends a `remediation-log.md` row), then run `verify-refactor` on the touched function(s). Close the row to `DONE` only on a **SAFE** verdict *and* the finding's own analysis confirming it resolved. `UNSAFE` / `UNKNOWN` blocks the row \u2014 never upgrade it to closed.\n3. **RE-AUDIT.** After the batch, invoke `architecture-audit` again. It folds the remediation log into the map, re-verifies each claimed fix against fresh structure, and surfaces the next layer. A claimed-RESOLVED finding the structure contradicts is a **regression** \u2014 it re-enters the queue as a new finding. Increment the cycle; return to step 2 with the new findings.\n4. Repeat until an AUDIT pass hits the step-1 stop condition.\n\n### Found-issue discipline (the generic rule still binds \u2014 and bites harder here)\n\nEvery issue an agent surfaces *during* the loop is in scope, exactly as in the generic loop: nothing is deferred as \"pre-existing\" or parked in a follow-ups list. **Do not assume the next audit will catch it** \u2014 the audit is structural-only, so anything outside the dependency graph is invisible to it and the tracker is its only durable home. Concretely, during REMEDIATE:\n\n- **Blocking** (the issue prevents closing the current finding correctly) \u2192 fix it inside that finding's remediation before its row reaches `DONE`.\n- **Non-blocking structural** finding the audit *will* independently re-confirm (a new cycle, a fresh god object) \u2192 append an `F-n` row now so it is tracked, even though the next RE-AUDIT will also surface it.\n- **Non-blocking non-structural** finding the audit will **not** resurface \u2014 a logic bug spotted while reading code, a `verify-refactor` `dropped_cleanup`, a missing test, or any `REVIEW` / `UNSAFE` / `UNKNOWN` verdict \u2014 **must** get an `F-n` row, because no future audit will recover it. A non-SAFE `verify-refactor` verdict is a found issue, never a warning to wave past.\n\n`F-n` rows live in the tracker's Findings table and carry the same closing discipline as audit-derived rows.\n\n### Ratchet invariants (what must never regress)\n\n- **The Refuted ledger is carried forward, never dropped** \u2014 disproven smells stay disproven across cycles.\n- **`remediation-log.md` is append-only** \u2014 one row per verified step, keyed to a finding ID; never rewritten or reordered.\n- **Trend is monotonic by construction** \u2014 the audit's improving/stable/degrading verdict is the ratchet read-out; a degrade is not silently tolerated, it becomes a finding and the loop pulls it back.\n- **Same-commit state updates still hold** \u2014 the tracker's cycle/phase row changes in the same commit as the work (or the log row) it records.\n\n### Named exclusions for the generated tracker\n\nA quality-loop tracker has **no authority-spec chain**, **no per-item spec premise re-verification** (the audit *is* the premise check), and **no static far-future queue** (each audit regenerates it). Name these exclusions in the generated file \u2014 silent omission of the spec sections looks like an oversight; a named exclusion is a decision."
}