meta-workflow

name	meta-workflow
description	Use at the start of any non-trivial task to run it as a closed loop instead of a straight line — classify the task's weight, clarify the real goal, freeze acceptance criteria before building, execute, then independently verify "done AND good enough" before delivering. Orchestrates the step sub-skills and hands execution to superpowers. Skip for chat, lookups, and trivial one-line edits.

Meta-Workflow — run heavy work as a closed loop

A meta-workflow for AI coding agents: deciding when work is heavy enough to deserve the loop, defining what "good" looks like before you build, and verifying you got there without grading your own homework. It uses superpowers as its execution dependency — the brainstorm / plan / TDD / review skills — a dependency, not a foundation; the execution layer could be swapped or self-built.

Why this exists

The default AI workflow is a straight line: understand → build → say done. It ships plausible-but-wrong work, for two reasons the line never addresses:

1. No bar. "It runs end-to-end" gets mistaken for "it's correct." Nothing was frozen up front to check against, so whatever came out becomes the definition of done.
2. Self-grading. The same agent that built it judges it. Confirmation bias here is structural, not a character flaw — in our own logs a detector self-reported 1.00 recall; an independent test measured 0.17.

So heavy work runs as a closed loop, and every dispatched sub-agent runs the same loop inside its own scope:

0 classify ─► ① clarify ─► ② freeze acceptance ─► ③ execute ─► ④ verify (independent) ─► ⑤ remediate
                                                                       │
                                       └──────────── loop until it passes ◄┘

The loop is not the point — the judgment at each step is. Every step below leads with why. Strip the why and you are left with bureaucracy.

How to run this — read before you start

This skill orchestrates; it does not execute the steps for you. Three rules separate running the loop from merely reading about it:

1. Invoke each step's sub-skill with the Skill tool. The ▸ Invoke markers below are real instructions, not decoration. Reading this overview does not count as running a step — the sub-skills carry detail these summaries deliberately omit. Do not substitute your memory of the gist for actually loading them.
2. Build a TodoWrite checklist first. Turn the steps that apply (per this task's weight) into a TodoWrite list and tick them off as you go, so a skipped step is visible.
3. This bundle has no hooks. Nothing auto-triggers or enforces any of this — if you don't invoke the steps, they don't happen. That is the accepted trade (see "On enforcement").

The steps

Step 0 — Classify the task (the throttle)

Why: not everything deserves the loop. The cost of process must stay below the cost of the mistake it prevents. Most messages are chat or one-line edits — running a full loop on those is its own failure mode. Do: decide what this is — chat / trivial edit / simple doc / design / build / exploration — and spend ceremony accordingly. Judge by blast radius, not by how long the request was: a one-line change to shared infrastructure (hooks, schedulers, data pipelines, eval) is heavy; a long question is not. When unsure, go heavier. ▸ Invoke task-classification.

Step ① — Clarify what you are really doing

Why: a means is not a goal. "Build an oracle" is a means; "the extractions are accurate" is the goal — chase the real one. And your measure must not depend on the thing it measures (don't judge extraction quality by the recall of that same extraction). Do: pin three things — the real goal, constraints + assumptions (each rated importance × certainty), and 1–3 success criteria each tagged measurable or judgment (give judgment ones a semi-objective anchor). Show them to the human before proceeding. ▸ Invoke clarify-intent. Then invoke superpowers brainstorming for solution exploration.

Step ② — Freeze acceptance criteria

Why: if you set the bar after seeing the result, you will set it wherever the result landed. Freezing is what makes "lower the bar to pass" detectable. Do: break the work into stages; for each write expected value × how to verify × measurable/judgment. Freeze it (the human confirms). After freezing you may only move the bar toward truth (the table itself was wrong), never down (it turned out hard) — adjudicate the difference with a time anchor: was the evidence available when you first set the value? ▸ After brainstorming, invoke superpowers writing-plans for the stage breakdown, then invoke freeze-acceptance to add the frozen bar. (This respects brainstorming's "the only skill you invoke next is writing-plans" terminal rule — freeze-acceptance runs after writing-plans, as the upstream judgment step wrapping the plan, not as a competing next-skill.)

Step ③ — Execute against the table

Why: the frozen table should pull the work the whole way, not sit in a drawer until review. Do: hand execution to superpowers. Carry each stage's expected value × how to verify into every sub-agent you dispatch — fractal: each runs the same loop in its scope and returns its own self-check. That self-check is step ③, not step ④. ▸ Invoke execute-with-spec for the hand-off convention, then delegate the actual work to superpowers executing-plans / subagent-driven-development / test-driven-development / systematic-debugging.

Step ④ — Verify "done AND good enough" — independently

Why: the builder cannot be the verifier. Their self-check already happened in ③; reusing it as the gate is the self-grading failure this whole loop exists to stop. Do: an independent reviewer (≠ the builder) checks each stage against the frozen table and issues a per-stage verdict. Metric claims — recall, precision, cost, coverage, latency — get the stricter gate in references/hard-gates.md: the reviewer recomputes ≥3 samples by hand and does not read the implementation first. ▸ Invoke independent-verify (it draws on references/hard-gates.md); use superpowers requesting-code-review / verification-before-completion for the mechanics.

Step ⑤ — Remediate

Why: a failed check has exactly three exits, and none of them is "ship it quietly." Do: pick one and leave a trace — (1) fix at root cause (don't suppress the symptom to make the verdict look better), (2) fix the table toward truth (with sign-off), or (3) accept with a known defect (recorded, with a recovery trigger). Re-verify after fixing. Default to one fix→recheck cycle; if it still fails, escalate to the human instead of looping forever. When the root cause is a recurring/process problem, push a prevention layer back upstream (see references/prevention-layers.md). ▸ Invoke remediation-loop; use superpowers receiving-code-review for the posture.

Decision flow

digraph meta_workflow {
  "Task arrives"        [shape=doublecircle];
  "Heavy enough?"       [shape=diamond];
  "Just do it"          [shape=box];
  "① clarify"           [shape=box];
  "② freeze table"      [shape=box];
  "③ execute"           [shape=box];
  "④ independent verify"[shape=box];
  "Pass?"               [shape=diamond];
  "⑤ remediate"         [shape=box];
  "Deliver"             [shape=doublecircle];

  "Task arrives" -> "Heavy enough?";
  "Heavy enough?" -> "Just do it"  [label="no (chat / trivial / touches nothing shared)"];
  "Heavy enough?" -> "① clarify"   [label="yes (design / build / touches shared infra)"];
  "① clarify" -> "② freeze table";
  "② freeze table" -> "③ execute";
  "③ execute" -> "④ independent verify";
  "④ independent verify" -> "Pass?";
  "Pass?" -> "Deliver"      [label="all gates pass"];
  "Pass?" -> "⑤ remediate"  [label="any fail"];
  "⑤ remediate" -> "④ independent verify" [label="re-check (max 1 cycle, then escalate)"];
}

Red flags — you are rationalizing

Thought	Reality
"It runs, so it's done."	Running ≠ meeting the bar you froze. Check the table.
"I'll know good when I see it."	Then you'll call whatever you see good. Freeze the bar first.
"I built it and it looks right."	You can't verify your own work. Get an independent check.
"This is just a small change."	Judge by blast radius. Touching shared infra is never small.
"The metric hit the target."	Did an independent recompute confirm it? Self-reported metrics lie.
"It's basically there, I'll lower the bar."	That's not aligning to truth, that's hiding a miss.

What's mine vs what's superpowers

Delegated to superpowers (install it; do not reinvent): brainstorming, writing-plans, executing-plans, subagent-driven-development, test-driven-development, systematic-debugging, requesting-code-review, verification-before-completion, receiving-code-review.

Added here (the judgment superpowers doesn't cover): task classification (the throttle), the three-piece intent clarification, frozen acceptance tables with the anti-lowering time anchor, the hard-gates truth table (especially the metric self-review ban), and the L1–L5 prevention-layer model for remediation.

How this runs — prompt-driven, not enforced

Meta-Workflow is lightweight by design: it ships no hooks, so nothing auto-triggers or hard-stops you — the discipline lives in the prompts, and you drive it. A model can read these skills and still skip a step; staying in the driver's seat is the trade for staying lightweight and portable. If you want hard enforcement — say, a gate that blocks delivery when a frozen acceptance table has no independent review — references/prevention-layers.md shows how to build it on your platform.