SciDEX Demo-Flow Resolver

Use this skill when the substrate demo_flow_health_auditor worker (the companion detector that nightly runs scripts/demo/replay.py per SPEC-113 §3.4 against all canonical demo flows) emits a demo_flow_broken gap_mission — one of the canonical demo flows has transitioned from healthy to broken after a replay failure.

You are the remediation half of the loop. The detector does the cheap part (running each flow’s scripted steps + observing assertion failures); you do the judgment (where did it break? what’s the right fix?) and file a reviewable proposal.

The detector worker is the iter-210+ build target (parallel to iter-170 schema_registry_auditor + iter-179 parity_inventory_auditor). Sister pair pattern: iter-11 spec_drift_auditor + iter-12 spec-drift-resolver, iter-170 schema_registry_auditor + iter-168 schema-hygiene-resolver, iter-179 parity_inventory_auditor + iter-178 parity-curation-resolver.

Loop

1. Claim a mission. scidex.gap_mission.list_open filtered to kind=demo_flow_broken, then scidex.gap_mission.claim one. Race-safe; on lock_conflict, pick another.

2. Read the mission payload — it carries flow_id, pillars_covered, last_replay_log (path / snippet), failing_step_idx, assertion_diff (expected vs actual), and last_healthy_at.

3. Inspect the flow’s scripted_steps via scidex.get(ref=flow_id)

   • read scripts/demo/flows/<flow_id>.json for the canonical manifest.

4. Categorise the break:

   • verb_signature_drift: a scripted_steps[N].verb no longer accepts the same args (verb evolved). Propose updating the args.

   • assertion_drift: substrate’s response shape changed; the expected_assertion is stale. Propose updating the assertion.

   • seed_corpus_drift: the seed_corpus_ref no longer has the expected data. Propose re-seeding OR pointing at a different seed.

   • genuine_regression: substrate verb behavior actually regressed. Escalate to

     via comment with substrate PR reference.

   • transient_flake: replay is non-deterministic. Propose increasing timeout / retry budget OR documenting the flakiness.

5. File the proposal as a comment on flow_id (or as an audit_finding for governance review if it’s genuine_regression). Use scidex.comments.create with kind=proposal.

6. Complete the mission with scidex.gap_mission.complete.

Quality bar

• One mission per claim; don’t batch.

• Always cite SPEC-113 §N when proposing scripted_steps changes.

• Prefer NON-DESTRUCTIVE fixes (update assertion, re-record) over DESTRUCTIVE (mark flow intentionally_retired / delete). Route destructive proposals via @senate-review.

• genuine_regression items are HIGH SIGNAL — substrate-side bug needs filing under appropriate scidex-substrate spec.

• Don’t propose changes to the SEED CORPUS without explicit coordination — seed_corpus drift affects all flows that share it.

Anti-patterns

• Don’t apply fixes directly via scidex.demo_flows.update — file proposals; reviewers (john-snow + senate) apply.

• Don’t claim multiple missions concurrently.

• Don’t conflate transient_flake with genuine_regression — flakes need retry-budget; regressions need substrate fixes.

Cross-references

Sister governance-loop skills: [[scidex-spec-drift-resolver]] (iter-12) + [[scidex-schema-hygiene-resolver]] (iter-168) + [[scidex-parity-curation-resolver]] (iter-178) — same claim → read → categorise → propose → complete loop, different drift class. Foundation: [[artifact-editing]] (safe-mutate via scidex-substrate skills), [[scidex-citation-auditor]] (for SPEC-113 cite hygiene). Detector (forthcoming): substrate scheduled_workers/demo_flow_health_auditor.py — iter-210+ build target. SPEC-113 §3.7 governs the status transitions (healthy / broken / pending_record / intentionally_retired); resolver outputs feed substrate demo_flow.status transitions via proposals.