building-a-workflow-spell

Building a Workflow Spell

What this does

Specialist builder for kind: workflow spells. A workflow has multiple stages with explicit handoff artifacts and checkpoints between them.

When to use

• Routed to from building-a-spell Stage 2 when kind: workflow
• User describes a process with natural stopping points and intermediate artifacts

What you bring (Inputs)

• The workflow's overall goal
• The natural stages (or the steps the user does today, which we'll cluster)
• The artifact handed from each stage to the next

What you get (Output)

A draft SKILL.md with explicit Stages, Checkpoints, and Loop-back conditions sections, ready for the standard tester.

How it works (Steps)

This is a workflow chain.

Stages

Stage 1: Identify the natural stopping points

A stage is a place where you could (and sometimes do) stop, hand the work to someone else, and return to it later.

Ask the user (or extract): "What are the natural stopping points in this process?"

If the user says "no stopping points, it's one continuous flow" — this isn't a workflow; it's a content kind. Re-route.

Stage 2: Name each stage and its artifact

Each stage has:

• Goal: what this stage accomplishes
• Input: artifact from the previous stage (or initial inputs for stage 1)
• Output: artifact handed to the next stage

If you can't name the output artifact, the stage isn't well-defined yet. Sharpen.

Stage 3: Write checkpoints

For each stage transition, write the checkpoint — what must be true to pass the gate.

Checkpoints are tested, not asserted. Each checkpoint should be verifiable: the artifact has a property you can check.

Stage 4: Identify loop-back conditions

A workflow without loop-backs is a pipeline (one-way). Most real workflows loop back — when the artifact at stage N reveals stage N-1 was wrong.

Capture loop-back conditions explicitly. If there are none, that's a finding — confirm with user.

Stage 5: If the workflow composes other spells, declare them

When stages are themselves named spells, add a composes field to frontmatter:

composes:
  - <constituent-spell-1>
  - <constituent-spell-2>

This makes the workflow a chain. See chaining-spells/SKILL.md for details on chain mechanics.

Stage 6: Hand off to standard tester

Standard mode (not discipline mode). Tester runs 2-3 scenarios end-to-end through all stages.

If a checkpoint repeatedly fails, that stage's checkpoint is wrong (too strict or too loose). Refine in Stage 3.

Stage 7: Hand back to meta-builder

Return the PASSing draft.

Checkpoints

• After Stage 1: at least 2 stopping points named (else re-route to content)
• After Stage 2: every stage has goal + input + output artifact
• After Stage 3: every stage transition has a verifiable checkpoint
• After Stage 4: loop-back conditions documented (or explicitly "none, this is a pipeline")
• After Stage 5: if composes is set, every name resolves to a real spell
• After Stage 6: tester returns PASS

Loop-back conditions

Return to Stage 2 when:

• A checkpoint can't be made verifiable — the stage's output artifact wasn't well-defined
• Tester finds two stages can't be cleanly separated — merge them

Quality bar

The draft is good enough when:

• Each stage has a named output artifact
• Each transition has a verifiable checkpoint
• Loop-back conditions are documented (even if empty)
• If composes is set, every name resolves
• Tester returns PASS on 2-3 end-to-end scenarios

Variations

• Linear pipeline (no loop-backs): document explicitly
• Tree workflow (branches): rare; document branch conditions in stages
• Re-entrant workflow (resumable from any stage): document state-restore inputs per stage

Example

Workflow: structured-literature-review
Stages:
  1. Define the question (output: 1-sentence research question)
  2. Snowball search (output: 20-30 candidate papers)
  3. Screen by abstract (output: 8-12 included papers)
  4. Extract findings (output: per-paper extraction sheet)
  5. Synthesize (output: 1-page synthesis)

Checkpoints:
  - After 1: question is single-sentence and falsifiable
  - After 2: candidate count >= 20
  - After 3: inclusion criteria documented
  - After 4: every included paper has a filled extraction sheet
  - After 5: synthesis cites every included paper

Loop-backs:
  - After 3: if <8 included, return to stage 2 (broaden search)
  - After 5: if synthesis exposes a contradiction, return to stage 4 (re-extract)