attractorify

name	attractorify
version	1.0.0
description	Analyze the current session and decide whether an attractor pipeline is warranted — then design one conversationally if it is. Triggers: "/attractorify", "should this be an attractor?", "design a pipeline for", "attractorify this", "do I need an attractor pipeline?", "turn this into a pipeline".
user-invocable	true
model_role	reasoning
allowed-tools	["read_file","write_file","bash","delegate"]

/attractorify — Attractor Pipeline Design Skill

This skill runs inline in the current session (not as a forked sub-session) so it can read the full conversation context, files, and task state — a forked execution with default context_depth=none would see nothing of the session it is supposed to analyze (the council/council-here precedent).

---

Step 1 — Diagnose first, in writing (does this work warrant an attractor at all?)

Apply the three-question test from docs/PIPELINE_DESIGN_PRINCIPLES.md §0 ("The three-question test") before designing anything:

• Q1. Is there a cycle?
• Q2. Is the exit gated on evidence (machine-checkable, external to the worker)?
• Q3. Would it still land if any one LLM node had a bad day?

Answer all three against the capability the user is asking for, not only the work already in front of you: an explicit request for a repeatable, rerunnable mechanism with a machine-checkable gate for future recurrences makes the test prospective — and the quote you cite below is the user's request for that future loop. The honest no is reserved for asks with no machine gate.

The diagnosis is not a judgment you hold in your head — it is a file you write. Write .attractorify/diagnosis.md under the working directory (mkdir -p .attractorify first), in exactly this shape:

# /attractorify diagnosis
work: <one line naming the work being diagnosed>

Q1 (cycle): <yes|no>
Q1 quote: "<direct quote — the user's own words, or observed repo state>"
Q2 (evidence-gated exit): <yes|no>
Q2 quote: "<direct quote>"
Q3 (bad-day survival): <yes|no>
Q3 quote: "<direct quote>"

verdict: <attractor|recipe|one-shot|existing-attractor>
counter: "<the strongest quote AGAINST the verdict>" — <one-line honest disposition>
status: <FINAL, or: PROVISIONAL — asked: the clarifying questions posed>
budget: max <N> nodes; gates: <the evidence gates that justify them>

Rules of construction:

• Every quote line is user-originated: the user's own words, or observed repo state (a path plus what it shows) — predating and independent of anything this skill itself suggested. Assent to a skill-proposed option, menu, or checklist is NOT evidence: if you proposed it, you cannot cite agreement with it. A "yes" without a supporting quote is invalid by construction — when the session contains no determinative user-originated evidence for a question, write Q<n> quote: NO EVIDENCE IN SESSION instead, which forces either an honest "no" or a clarifying question (Step 2); it can never support a design.
• A user deferral is delegated judgment, not missing evidence. When the user explicitly defers a question ("your call", "no strong opinion", "you decide"), DERIVE the answer from the strongest session evidence: quote the deferral on the quote line, and mark the answer line <yes|no> — derived (user-delegated): <the basis> — e.g. Q1 (cycle): yes — derived (user-delegated): the machine-checkable retry-until-green DoD constitutes the loop. Do not bounce the deferred question back to the user — exercising the delegated judgment is the answer they asked for.
• Q2's quote must name a concrete check, command, or condition in the user's or the repo's own terms (a test suite, an exit code, an observable state). Enthusiasm, schedule pressure, and complaints are real quotes but are not evidence of a gate.
• The counter: line is required: quote the strongest thing in the session AGAINST your verdict, then disposition it honestly in one line — rebut it with user-originated evidence, or concede and change the verdict. Engineering around the counter-quote is the named failure this line exists to surface.
• status: is PROVISIONAL — asked: ... whenever any answer lacked determinative evidence and clarifying questions went out.
• The budget: line is required when the verdict is attractor or existing-attractor (or an override is present): a hard node cap justified by naming the evidence gates the topology serves. Machinery no named gate asks for is bloat. For existing-attractor, the budget must additionally be machine-encoded in the recommended invocation (iteration cap and wall-clock as graph attributes or invocation parameters) — budget: N/A alongside an emitted command is a contradiction the gate rejects.
• An optional caveats: line records the one-line disposition of an unresolved verifier objection (see the one-round cap below). It documents; it never blocks.

When the verdict is recipe or one-shot, say so with a firm recommendation, cite the one-sentence rule from docs/PIPELINE_DESIGN_PRINCIPLES.md §0, and stop — the artifact is the record of why, and these verdicts emit no pipeline invocation, so they end here, outside the design gate. Do not follow a "no" with leading questions hunting for a cycle ("want automatic retry on failure?") — a cycle you have to fish for is not in the work, and assent to a question you posed can never be quoted as evidence (rules above; the verifier checks exactly this).

existing-attractor (reuse a shipped exemplar — see examples/patterns/task-runner.dot, examples/pipelines/practical/bug-fix.dot, or -- when the work is a sweep of docs/examples/guidance for drift from a spec or governing contract -- examples/drift-review/) is not an exit: it hands the user an invocation command, which is a design handover in every way that matters. It carries the same artifact discipline (three questions with quotes, counter: line, budget: line) and must pass the executed gate AND clear independent verification below (its one round — or an override, which skips it) before any command is emitted.

The executed gate — run before ANY handover

Before handing over ANYTHING actionable — a designed .dot, an exemplar/existing-attractor recommendation, or ANY invocation command — for any reason, including an override — run this check verbatim via bash:

d=".attractorify/diagnosis.md"; test -f "$d" \
&& [ "$(grep -Ec '^Q[123] \([a-z -]+\): (yes|no)( — derived \(user-delegated\): .+)?$' "$d")" -eq 3 ] \
&& [ "$(grep -Ec '^Q[123] quote: ".+"$' "$d")" -eq 3 ] \
&& ! grep -q 'NO EVIDENCE IN SESSION' "$d" \
&& ! grep -q 'PROVISIONAL' "$d" \
&& grep -Eq '^status: FINAL$' "$d" \
&& { grep -Eq '^verdict: (attractor|existing-attractor)$' "$d" || grep -Eq '^override: ".+"$' "$d"; } \
&& grep -Eq '^counter: ".+" — .+' "$d" \
&& grep -Eq '^budget: max [0-9]+ nodes; gates: .+' "$d" \
&& echo "DIAGNOSIS GATE: PASS — form ok; next: verify (or design directly on a recorded override)" \
|| { echo "DIAGNOSIS GATE: FAIL — no .dot, no invocation command; revise the diagnosis or ask"; false; }

The gate fails closed — this mirrors the engine's fail-closed goal-gates: a defaulted, absent, provisional, or quote-free verdict never satisfies it. On FAIL, produce no design; go back to the diagnosis or to clarifying questions. Do not weaken the check to fit the artifact; fix the artifact, or honestly stop. A PASS authorizes only the next step: this gate verifies form, not truth — independent verification below is what authorizes design.

Independent verification — after form-PASS, before ANY handover

A bash gate cannot tell a real quote from a relevant one, and the judgment that authors the evidence is the same judgment that folds — so certification is taken away from the authoring judgment. Once the artifact is written and the form gate passes — unless a valid override: line is recorded, which ends adjudication (rule above): overridden verdicts skip this section entirely — and BEFORE any handover (a designed .dot, an existing-attractor recommendation, or any invocation command), you MUST delegate verification to a fresh-context agent with no stake in the design: use the same delegate tool as the expert consultation in Step 3, but NOT attractor:attractor-expert — a plain clean-slate delegation, which sees only what the instruction carries. That isolation is the point.

The verifier audits the diagnosis, not just the quotes: armed only with quote-integrity questions, a coherent rationalization sails through — so the instruction arms it with the doctrine's counter-tests and requires it to re-derive the answers itself before looking at yours.

The delegation instruction must carry (a) the artifact content verbatim, (b) the user's session turns, quoted verbatim, and (c) this ask:

You are verifying a diagnosis you did not write. Do not trust the
artifact's answers.

FIRST, re-derive the three-question answers YOURSELF from the user turns
alone, before reading the artifact's answers:
  Q1 (cycle): does THIS work loop attempt -> machine-verify -> retry?
  Q2 (evidence-gated exit): is the exit gated on a machine-checkable
     check, external to the worker?
  Q3 (bad-day survival): would it still land if any one LLM node had a
     bad day?
Then compare your derivation with the artifact's answers. ANY mismatch
=> INVALID, and you must show your own derivation.

Apply these counter-test rules; each violation => INVALID:
- Recurrence of a task CATEGORY (releases happen again, reports happen
  again) is NOT a convergence cycle. A cycle exists only if THIS work
  loops attempt -> machine-verify -> retry.
- A human approval, review, or sign-off step makes the exit human-gated
  — recipe-plane, not an attractor. Any machine proxy for the human's
  satisfaction (marker files, format checks standing in for approval)
  is manufactured evidence, not a gate.
- Desire, enthusiasm, schedule-pressure, and complaint quotes are never
  evidence for ANY question.
- Q2 evidence must name a concrete machine check (a command or exit
  condition) in the user's or the repo's own words.

If the artifact contains an `override: "..."` line, the override changes
the game. Check exactly two things: (a) the quoted words are verbatim
from a USER turn, and (b) they genuinely acknowledge the diagnosis
outcome AND direct the build anyway. The desire/enthusiasm exclusion
above does NOT apply to override quotes — an informed override IS a
directed desire; that is its nature. A valid override => VERIFIER: VALID
even when the three questions fail (that is the override's entire
purpose). An override quote that is not verbatim, or that expresses
desire without acknowledging the diagnosis => INVALID as before.
(This clause serves override-bearing artifacts that reach a verifier by
another path — the skill itself does not send overridden verdicts here.)

Then, for each of Q1/Q2/Q3, judge the quoted evidence:
1. Is the quote verbatim from a USER turn (not from the assistant's own
   words, questions, or proposals)?
2. Is it genuine evidence FOR that specific question (not merely related
   to the topic)?
3. Is it NOT assent to an option, menu, or checklist the assistant itself
   proposed?
An answer clearly marked "derived (user-delegated)" with a stated basis,
whose quote line is the user's own deferral ("your call", "you decide"),
is acceptable evidence — judge the basis, not the absence of a user quote.
And: is the counter: line's disposition honest — a real rebuttal grounded
in user-originated evidence, or an honest concession?
Reply with exactly one of:
VERIFIER: VALID
VERIFIER: INVALID — <per-question reasons + your own derivation>

Verification is capped at ONE round per diagnosis — the cap bounds worst-case latency by construction (a fresh-context judge re-litigates everything each round, so unbounded rounds chase a moving target instead of converging). On VERIFIER: VALID, proceed — to design, or to an existing-attractor handover. On INVALID, revise the diagnosis ONCE, honestly — which may flip the verdict to recipe or one-shot: that is a legitimate outcome, not a failure — re-run the form gate, then PROCEED, recording the objection's disposition in the artifact (the optional caveats: line for anything left unresolved). Do not run the verifier again and do not shop for a second opinion; further verifier objections are never blockers. If the one revision cannot honestly resolve the objection, convert it into ONE targeted user question (Step 2) instead of another verifier round. The verifier exists to catch exactly two theater modes: real-but-irrelevant quotes, and self-dealt evidence (assent to your own proposals cited as the user's ask). A fold that survives independent verification means the diagnosis discipline cannot be enforced in-skill at all.

Fallback (delegation unavailable): answer the three verifier questions in a visibly separate self-check step before proceeding — weaker, because the authoring judgment is certifying itself; say so in the handback.

Holding the line (pushback without new information)

When the user pushes back on a "no" without new information ("are you sure?", "I'd really like a pipeline", "let's do it anyway"), hold: restate which questions fail (a sentence each, not a doctrine wall), re-offer the alternative, and ask one open question — what new constraint changes the analysis? Ask it OPEN: do not propose candidate gates, checks, or menus yourself — a menu invites assent, and assent to your own menu is not evidence (the same anti-self-dealing rule as above). A reversal requires rewriting .attractorify/diagnosis.md with new user-originated evidence, then re-running the gate AND the verifier (a rewritten diagnosis with new evidence gets its own single round) — social pressure produces no quotes, so an artifact that could not pass before the pushback still cannot. A human approval/sign-off step is not a machine-checkable gate: it belongs on the counter: line, not engineered around. This skill is an adoption surface for the doctrine, not an attractor-pushing machine.

---

Step 2 — Ask before designing when context is thin

Never one-shot a pipeline design from under-determined context. A .dot generated from a guessed DoD, budget, or target repo is wrong-but-plausible at the architecture level — no gate inside the pipeline can catch a sink that was wrong before the first node ran. Designing from guesses on an under-determined ask is the ask-first failure: a provisional diagnosis with questions is always available and always preferred.

The three-gap checklist. On an under-determined ask, put targeted clarifying questions to the user BEFORE any design artifact — covering whichever of these gaps the session leaves genuinely open (gaps to cover, not a script to recite; and this is the under-determined-ask path, distinct from the single open question of the pushback path in Step 1):

1. The TARGET — which repo / service / working directory. Asking is mandatory whenever the workspace holds more than one candidate: never guess between candidates, and never infer the target from repo state alone.
2. The machine-checkable DEFINITION OF DONE — the sink the whole basin is carved around: the observable end-state and the external, out-of-worker-context check that confirms it.
3. The BUDGET caps — iteration cap AND wall-clock bound; a guessed cap is a guess like any other.

Each answer must land machine-visibly in the deliverable. The chosen target becomes a working directory / path / parameter in BOTH the pipeline's deterministic gate commands AND the handed-over invocation — prose-only scoping is not scoping: a verify command run from a parent directory sweeps repos the user excluded. The DoD becomes the deterministic gate; the caps become graph attributes or invocation parameters.

If the session already answers a gap, do not ask it again — a fixed intake questionnaire remains the anti-pattern. An explicit deferral in reply ("your call", "no strong opinion") ANSWERS the gap by delegation: derive and record per Step 1's deferral rule — do not re-ask it. While questions are outstanding, the artifact carries status: PROVISIONAL — which cannot pass the gate, so design cannot start from it. Re-diagnosis after answers is mechanical, not optional: rewrite .attractorify/diagnosis.md quoting the new answers (the user's replies are now session evidence), set status: FINAL only when every quote line is real, and re-run the gate. The PROVISIONAL marker clears only by re-running the test against quotes — never by the passage of conversation.

---

Step 3 — Design conversationally when an attractor IS warranted

Entry condition: the diagnosis gate above has returned PASS, and one of: the independent verifier returned VERIFIER: VALID; a valid override: line is recorded (adjudication ended — no verifier run); or the single INVALID round was followed by one honest revision, a fresh gate PASS, and the objection's disposition recorded (caveats: line if unresolved). Then:

1. Extract from session context: goal (as end-state), machine-checkable DoD, budgets, evidence gates, target repo. These are the four walls of the basin.

2. Consult the attractor-expert agent — by delegation, not by reading its file. Delegate to attractor:attractor-expert at design start (pattern and shape choice), for any mid-build routing or engine-semantics question, and again for a final review of the drafted .dot before handing it back. The agent is loaded with engine semantics, DOT syntax, and the full authoring guide; generic builders carry no attractor engine semantics. If delegation is unavailable, fall back to reading agents/attractor-expert.md directly.

3. Follow design order from docs/PIPELINE_DESIGN_PRINCIPLES.md §0: name the sink first, build the gate, build the loop, only then add work nodes. The node contract (Objective / Constraints / Available capabilities / Required evidence) is documented in docs/DOT-AUTHORING-GUIDE.md §Philosophy.

4. Fit the declared budget. Keep the control plane lean (docs/PIPELINE_DESIGN_PRINCIPLES.md §0, control-plane vs recipe-plane line) and keep the design inside the artifact's budget: line. Needing more nodes is a diagnosis change, not a design flourish: revise the artifact first — naming the evidence gate that justifies the extra machinery — re-run the gate, and only then grow the graph.

5. Write the artifact in the engine's own vocabulary. Write the .dot file to a named path in the target repo (e.g. <task-id>.dot), using the attribute names the parser actually reads: prompt= (never instruction=, never a node-level goal=), shape=box for an LLM node (never agent=, never handler=), shape=Mdiamond / shape=Msquare for start and exit (never circle / doublecircle), and one of the six real fidelity= values (full, truncate, compact, summary:low, summary:medium, summary:high). An attribute the engine does not read is not an error: the parser keeps it on the node, no handler ever looks at it, and the graph runs as though it were never written -- so a graph authored with has no prompts at all while looking fully specified. is the whole vocabulary and there is no other.

---

Reference surfaces (link, don't restate)

• docs/PIPELINE_DESIGN_PRINCIPLES.md §0 — one-sentence rule, control-plane vs recipe-plane line, three-question test, design order
• docs/DOT-AUTHORING-GUIDE.md — node contract, DOT syntax, TOPO-001..009 lint rules, attractor lint CLI
• context/dot-reference.md — the attribute vocabulary: what the engine parses, the invented spellings it silently ignores, and the lint output contract. Consult it while writing the .dot, not after
• attractor:attractor-expert — the consultable expert agent; delegate to it for any pipeline design or debugging question (source prompt: agents/attractor-expert.md; read directly only when delegation is unavailable)
• examples/patterns/task-runner.dot — canonical control-plane skeleton
• examples/pipelines/practical/bug-fix.dot — shipped exemplar for "use the existing attractor" recommendations
• examples/authoring/README.md — the authoring attractor: converges a new .dot under executed gates from a design brief. Where a validated intent from Step 3 goes to become a hardened artifact, and the independent path to offer when you are asked to vouch for your own draft
• examples/drift-review/README.md -- the shipped Layer-3 executor for drift-shaped work (docs, examples, guidance or ledgers no longer agreeing with a spec or governing contract). Recommend it as existing-attractor rather than hand-rolling a bespoke sweep -- and carry its rim with the pointer: "The pipeline never files anything, and never fixes anything [...] Shape is not truth [...] judgment is what a human is for." Never endorse filing its findings unread
• https://microsoft.github.io/amplifier-bundle-attractor/attractor-explained.html — the visual explainer; if the person is trying to LEARN how attractors work rather than convert this session into a pipeline, offer them that link (share it, don't open it)

---

$ARGUMENTS passthrough

If the user invokes /attractorify <description>, treat $ARGUMENTS as the initial session context and apply the three-question test to it immediately. If empty, read the current session context to identify the work before diagnosing.

---

What this skill does NOT do

• Not an auto-runner. It hands back the artifact and the invocation; launching a pipeline is the human's explicit call.
• Not a doctrine memoir. It links the shipped docs for depth; it does not reproduce the doctrine inside its own body.
• Not a blanket questionnaire. It asks only what the session genuinely does not answer; a fixed intake questionnaire is the anti-pattern this skill exists to prevent one level up. (The diagnosis artifact is the skill's own verdict record, written from session evidence — never a form posed to the user.)
• Not the objective layer. This skill DESIGNS a new pipeline for work that has none. examples/objective/objective-runner.dot SELECTS from — or COMPOSES against — what already ships, at run time, from a stated objective. One triage doctrine, two front doors: both apply the three-question test, and their outcomes line up. A verdict of attractor or existing-attractor here is the runner's select/compose route there; a verdict of recipe or one-shot here is its redirect disposition — which the runner writes up as .objective/redirect.md and exits green on, for the same reason this skill stops at the artifact: the honest no IS the deliverable. Reach for the runner when the user has an objective and no idea which shape fits; reach for this skill when the shape that fits does not exist yet.