flow-failure-response

Diagnose runtime probe flow failures and route fixes between code changes and lead escalation.

Updated Apr 7, 2026
One-click install
npx skills add https://github.com/hontauadrian/sfx-app-empty-test --skill flow-failure-response-hontauadrian
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: flow-failure-response
Source: https://github.com/hontauadrian/sfx-app-empty-test/tree/main/.claude/skills/flow-failure-response
Command: npx skills add https://github.com/hontauadrian/sfx-app-empty-test --skill flow-failure-response-hontauadrian

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When a runtime smoke probe fails on a flow contract you do not own, builder agents need a deterministic response path: fix their own implementation or escalate to the lead, without ever editing protected flow files. ## Core Features & Use Cases - Decision tree for probe failures: Maps FLOW_STEP_FAILED, FLOW_NEW_ENDPOINT_UNCOVERED, FLOW_OWNERSHIP_VIOLATION, FLOW_MERGE_CONFLICT, FLOW_DUPLICATE_ID, and FLOW_FILE_MISSING_OWNS_OR_EXTENDS diagnostics to the correct action. - Option A code-fix workflow: Guides reading the failing flow's expected status, body shape, side-effects, and capture bindings, then fixing the controller, service, or DTO and re-running pnpm probe:smoke. - Option B lead escalation: Provides ready-to-send ov mail flow_mismatch templates with probe output, spec citations, and proposed flow changes, plus handling of the worker-done pre-close gate. - Use Case: A builder's commit is blocked by FLOW_NEW_ENDPOINT_UNCOVERED after adding an endpoint; the skill directs them to mail the lead with the endpoint shape instead of editing the flow file. ## Quick Start When pnpm probe:smoke reports a FLOW_STEP_FAILED or FLOW_NEW_ENDPOINT_UNCOVERED error, invoke this skill to decide whether to fix my code or mail the lead.

Frequently Asked Questions about flow-failure-response

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I respond to a FLOW_STEP_FAILED probe error?▼

Read the failing flow file at .overstory/runtime-contract.flows/<task-id>.json to see the expected status, body, and captures, then fix the controller, service, or DTO causing the mismatch. Re-run pnpm probe:smoke until the flow passes; do not edit the flow file.

What should I do when the probe reports FLOW_NEW_ENDPOINT_UNCOVERED?▼

Send a flow_mismatch mail to the lead listing the new endpoint's method, path, DTOs, declared statuses, and side-effects. The lead authors flow coverage and replies with flow_update, which clears the pre-close gate.

Can I edit flow files to fix a probe failure myself?▼

No. The flows-path-boundary.js hook blocks Write, Edit, MultiEdit, NotebookEdit, and even shell writes against .overstory/runtime-contract.flows/, emitting FLOW_OWNERSHIP_VIOLATION. Only the lead can author flow changes.

Why is my git commit or worker_done blocked after a probe failure?▼

The flows-drift-check.js hook blocks commits when your diff adds endpoints no flow covers, and worker-done-evidence.js blocks closure while a flow_mismatch thread awaits the lead's reply. Bypassing with --no-verify is flagged at review.

When should I escalate a flow failure instead of fixing code?▼

Escalate when the flow's expectation provably contradicts the spec, when ownership or drift hooks block you, or when loader diagnostics like FLOW_MERGE_CONFLICT or FLOW_DUPLICATE_ID appear. If the lead is unresponsive, escalate to the coordinator with flow_escalation.